May 2019

Create world map charts with svgMap

svgMap is a JavaScript library that lets you easily create an interactable world map comparing customizable data for each country.

Install

ES6

You can install svgMap via npm:

npm install --save svgmap

import svgMap from 'svgmap';
import 'svgmap/dist/svgMap.min.css';

CDN

jsDelivr is a great CDN choice for svgMap:

<script src="https://cdn.jsdelivr.net/npm/svg-pan-zoom@3.6.1/dist/svg-pan-zoom.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/StephanWagner/svgMap@v2.7.2/dist/svgMap.min.js"></script>
<link href="https://cdn.jsdelivr.net/gh/StephanWagner/svgMap@v2.7.2/dist/svgMap.min.css" rel="stylesheet">

Usage

Create an HTML element where to show your map, then use JavaScript to initialize:

<div id="svgMap"></div>

new svgMap({
  targetElementID: 'svgMap',
  data: {
    data: {
      gdp: {
        name: 'GDP per capita',
        format: '{0} USD',
        thousandSeparator: ',',
        thresholdMax: 50000,
        thresholdMin: 1000
      },
      change: {
        name: 'Change to year before',
        format: '{0} %'
      }
    },
    applyData: 'gdp',
    values: {
      AF: {gdp: 587, change: 4.73},
      AL: {gdp: 4583, change: 11.09},
      DZ: {gdp: 4293, change: 10.01}
      // ...
    }
  }
});

This example code creates a world map with the GDP per capita and its change to the previous year:

Options

You can pass the following options into svgMap:

targetElementID	string	The ID of the element where the world map will render Required
minZoom maxZoom	float	Minimal and maximal zoom level Default: 1 for minZoom, 25 for maxZoom
initialZoom	float	Initial zoom level Default: 1.06
initialPan	object	Initial pan on x and y axis, e.g. { x: 120, y: 60 } Default: { x: 0, y: 0 }
zoomScaleSensitivity	float	Sensitivity when zooming Default: 0.2
mouseWheelZoomEnabled	boolean	Enables or disables zooming with the scroll wheel Default: true
mouseWheelZoomWithKey	boolean	Allow zooming only when one of the following keys is pressed: SHIFT, CONTROL, ALT, COMMAND, OPTION Default: false
mouseWheelKeyMessage	string	The message when trying to scroll without a key Default: 'Press the [ALT] key to zoom'
mouseWheelKeyMessageMac	string	The message when trying to scroll without a key on MacOS Default: 'Press the [COMMAND] key to zoom'
colorMax colorMin colorNoData	string	Color for highest value colorMax, lowest value colorMin and no data available colorNoData Default: '#CC0033', '#FFE5D9', '#E2E2E2'
flagType	'emoji', 'image'	The type of the flag in the tooltip Default: 'image'
flagURL	string	The URL to the flags when using flag type 'image'. The placeholder {0} will get replaced with the lowercase ISO 3166-1 alpha-2 country code Default: 'https://cdn.jsdelivr.net/gh/hjnilsson/country-flags@latest/svg/{0}.svg'
hideFlag	boolean	Hide the flag in tooltips Default: false
noDataText	string	The text to be shown when no data is present Default: 'No data available'
touchLink	boolean	Set to true to open the link (see data.values.link) on mobile devices, by default the tooltip will be shown.
onGetTooltip	function	Called when a tooltip is created to custimize the tooltip content (function (tooltipDiv, countryID, countryValues) { return 'Custom HTML'; })
countries: { // ... }		Additional options specific to countries:
↳ EH	boolean	When set to false, Western Sahara (EH) will be combined with Morocco (MA) Default: true
↳ Crimea	'UA', 'RU'	Crimea: Set to 'RU' to make the Crimea part of Russia, by default it is part of the Ukraine Default: 'UA'
data: { // ... }		The chart data to use for coloring and to show in the tooltip. Use a unique data-id as key and provide following options as value:
↳ name	string	The name of the data, it will be shown in the tooltip
↳ format	string	The format for the data value, {0} will be replaced with the actual value
↳ thousandSeparator	string	The character to use as thousand separator Default: ','
↳ thresholdMax	number	Maximal value to use for coloring calculations
↳ thresholdMin	number	Minimum value to use for coloring calculations
↳ applyData	string	The ID (key) of the data that will be used for coloring
↳ values	object	An object with the ISO 3166-1 alpha-2 country code as key and the chart data for each country as value
↳ color	string	Forces a color for this country
↳ link	string	An URL to redirect to when clicking the country
↳ linkTarget	string	The target of the link. By default the link will be opened in the same tab. Use '_blank' to open the link in a new tab
countryNames	object	An object with the ISO 3166-1 alpha-2 country code as key and the country name as value

Localize

Use the option countryNames to translate country names. In the folder demo/html/local you can find translations in following languages:
Arabic, Chinese, English, French, German, Hindi, Portuguese, Russian, Spanish, Urdu

To create your own translations, check out country-list by Saša Stamenković.

Attribution

If you need more detailed maps or more options for your data, there is a great open source project called datawrapper out there, with a lot more power than svgMap. Highmaps is also a great alternative.

svgMap uses svg-pan-zoom by Anders Riutta.

The country flag images are from country-flags by Hampus Nilsson.

Most data in the demos was taken from Wikipedia.