Overview

jVectorMap is a jQuery plugin employed to show vector maps and visualize data on HTML pages. It uses SVG in all modern browsers like Firefox 3 or 4, Safari, Chrome, Opera, IE9, while legacy support for older versions of IE from 6 to 8 is provided with VML. Using jVectorMap is pretty simple as for any other jQuery plugin. All you need is to connect JavaScript and CSS files of the plugin:

<link href="jquery.vector-map.css" media="screen" rel="stylesheet" type="text/css" />
<script src="jquery.vector-map.js" type="text/javascript"></script>
<script src="world-en.js" type="text/javascript"></script>

And then initialize it using some element as a container:

$(function(){
    $('#map').vectorMap();
});

So you can get something like this:

Now you can provide various parameters to the initialization function to customize look and behavior of the map. You can find description of all available parameters in the reference.

Reference

Parameters

While initializing map you can provide parameters to change its look and feel.

color #ffffff
Color of map regions.
hoverColor black
Color of the region when mouse pointer is over it.
hoverOpacity
Opacity of the region when mouse pointer is over it.
backgroundColor #505050
Background color of map container in any CSS compatible format.
colors
Colors of individual map regions. Keys of the colors objects are country codes according to ISO 3166-1 alpha-2 standard. Keys of colors must be in lower case.
scaleColors ['#b6d6ff', '#005ace']
This option defines colors, with which regions will be painted when you set option values. Array scaleColors can have more then two elements. Elements should be strings representing colors in RGB hex format.
normalizeFunction 'linear'
This function can be used to improve results of visualizations for data with non-linear nature. Function gets raw value as the first parameter and should return value which will be used in calculations of color, with which particular region will be painted.
onLabelShow
Callback function which will be called before label is shown. Label DOM object and country code will be passed to the callback as arguments.
onRegionOver
Callback function which will be called when the mouse cursor enters the region path. Country code will be passed to the callback as argument.
onRegionOut
Callback function which will be called when the mouse cursor leaves the region path. Country code will be passed to the callback as argument.
onRegionClick
Callback function which will be called when the user clicks the region path. Country code will be passed to the callback as argument.

Dynamic changing of the options

Most of the options can be changed after initialization using the following code:

$('#map').vectorMap('set', 'colors', {us: '#0000ff'});

Instead of colors can be used any parameter except callbacks. Callbacks can be added and deleted using standard jQuery patterns of working with events.

Events

You can define callback function when you initialize jVectorMap:

$('#map-events').vectorMap({
    onLabelShow: function(event, label, code){},
    onRegionOver: function(event, code){},
    onRegionOut: function(event, code){},
    onRegionClick: function(event, code){}
});

Or later using standard jQuery mechanism:

$('#map-events').bind('labelShow.jvectormap', function(event, label, code){})
$('#map-events').bind('regionMouseOver.jvectormap', function(){event, code})
$('#map-events').bind('regionMouseOut.jvectormap', function(){event, code})
$('#map-events').bind('regionClick.jvectormap', function(){event, code})

Consider that fact that you can use standart features of jQuery events like event.preventDefault() or returning false from the callback to prevent default behavior of jVectorMap (showing label or changing country color on hover). In the following example, when user moves mouse cursor over Canada label won't be shown and color of country won't be changed. At the same label for Russia will have custom text.

$('#map-events').vectorMap({
    onLabelShow: function(event, label, code){
        if (code == 'ca') {
            event.preventDefault();
        } else if (code == 'ru') {
            label.text('Bears, vodka, balalaika');
        }
    },
    onRegionOver: function(event, code){
        if (code == 'ca') {
            event.preventDefault();
        }
    },
});

Data visualization with jVectorMap

Here I want to demonstrate how visualization of some geographical-related data can be done using jVectorMap. Let's visualize information about GDP in 2010 for every country. At first we need some data. Let it be site of International Monetary Fond. There we can get information in xsl format, which can be converted first to csv and then to json with any scripting language. Now we have file gdp-data.js with such content (globals are evil, I know, but just for the sake of simplification):

var gdpData = {"af":16.63,"al":11.58,"dz":158.97,...}

Then connect it to the page and add some code to make visualization:

var max = 0,
    min = Number.MAX_VALUE,
    cc,
    startColor = [200, 238, 255],
    endColor = [0, 100, 145],
    colors = {},
    hex;
//find maximum and minimum values
for (cc in gdpData) {
    if (parseFloat(gdpData[cc]) > max) {
        max = parseFloat(gdpData[cc]);
    }
    if (parseFloat(gdpData[cc]) < min) {
        min = parseFloat(gdpData[cc]);
    }
}
//set colors according to values of GDP
for (cc in gdpData) {
    if (gdpData[cc] > 0) {
        colors[cc] = '#';
        for (var i = 0; i<3; i++) {
            hex = Math.round(startColor[i] + (endColor[i] - startColor[i])*(gdpData[cc] / (max - min))).toString(16);
            if (hex.length == 1) {
                hex = '0'+hex;
            }
            colors[cc] += (hex.length == 1 ? '0' : '') + hex;
        }
    }
}
//initialize jVectorMap
$('#example-map-2').vectorMap({
    colors: colors,
    hoverOpacity: 0.7,
    hoverColor: false
});

Here is the result:

Not really hard I think. But we have two problems. At first it's necessary to write some code and also we got not really helpful visualization, because most of countries hove about the same color. This happens because linear function was used to convert values to colors, but data rarely has linear nature. So we need to use some non-linear scale to visualize data. Fortunately jVectorMap has functionality to resolve both these problems by simply providing additional parameters to initialization function.

$('#example-map-3').vectorMap({
    values: gdpData,
    scaleColors: ['#C8EEFF', '#006491'],
    normalizeFunction: 'polynomial',
    hoverOpacity: 0.7,
    hoverColor: false
});

Looks much more informative now!

Maps

Two additional vector maps are available: USA and Germany. They are included in standard package.

$('#map-usa').vectorMap({map: 'usa_en'});


$('#map-germany').vectorMap({map: 'germany_en'});


$('#map-usa').vectorMap({map: 'europe_en'});

Download

You can download jVectorMap here.

Also jVectorMap available on github.

Contacts

If you have any questions about library or need any help, don't hesitate to email me at echo.bjornd@gmail.com. Any suggestions and feature requests are welcome too.

Also follow me on twitter.