JavaScript Library For Interactive Vector Maps – jsvectormap

A plain JavaScript library for rendering an interactive, dynamic, vector-shaped world map on the page.

More Features:

• Clickable countries, regions.
• Custom markers, labels, and tooltips.
• Smooth pan & zoom.
• Custom styles.
• Touch-friendly.

How to use it:

1. Load the jsvectormap.css and jsvectormap.js on the HTML page.

<link rel="stylesheet" href="./dist/jsvectormap.css" />
<script src="./dist/jsvectormap.min.js"></script>

2. Create a placeholder for the vector map.

<div id="map"></div>

3. Load map data into the document.

<script src="./dist/maps/world.js"></script>

<script src="./dist/maps/world-merc.js"></script>

4. Render a map of the world with clickable regions.

var map = new jsVectorMap({
    map: 'world', // 'canada', ...
    selector: '#map', 
})

5. Config the map with the following parameters:

var map = new JsVectorMap({
    // world_merc, us_mill_en, us_merc_en,
    // us_lcc_en, us_aea_en, spain
    // russia, canada, iraq
    map: 'world',
    backgroundColor: 'tranparent',
    draggable: true,
    zoomButtons: true,
    zoomOnScroll: true,
    zoomOnScrollSpeed: 3,
    zoomMax: 12,
    zoomMin: 1,
    zoomAnimate: true,
    showTooltip: true,
    zoomStep: 1.5,
    bindTouchEvents: true,
    // Line options
    lineStyle: {
      stroke: '#808080',
      strokeWidth: 1,
      strokeLinecap: 'round'
    },
    focusOn: {}, // focus on regions on page load
    /**
     * Markers options
     */
    markers: null, // Set of markers to add to the map during initialization
    markersSelectable: false,
    markersSelectableOne: false,
    markerStyle: {
      initial: {
        r: 7,
        fill: '#374151',
        fillOpacity: 1,
        stroke: '#FFF',
        strokeWidth: 5,
        strokeOpacity: .5
      },
      hover: {
        fill: '#3cc0ff',
        cursor: 'pointer'
      },
      selected: {
        fill: 'blue'
      },
      selectedHover: {}
    },
    markerLabelStyle: {
      initial: {
        fontFamily: 'Verdana',
        fontSize: 12,
        fontWeight: 500,
        cursor: 'default',
        fill: '#374151'
      },
      hover: {
        cursor: 'pointer'
      },
      selected: {},
      selectedHover: {}
    },
    /**
     * Region styles
     */
    labels: { // add a label for a specific region
      regions: {
        render(code) {
          return ['EG', 'KZ', 'CN'].indexOf(code) > -1 ? 'Hello ' + code : ''
        },
      }
    }
    regionsSelectable: false,
    regionsSelectableOne: false,
    regionStyle: {
      // Region style
      initial: {
        fill: '#e3eaef',
        fillOpacity: 1,
        stroke: 'none',
        strokeWidth: 0,
        strokeOpacity: 1
      },
      hover: {
        fillOpacity: .7,
        cursor: 'pointer'
      },
      selected: {
        fill: '#000'
      },
      selectedHover: {}
    },
    // Region label style
    regionLabelStyle: {
      initial: {
        fontFamily: 'Verdana',
        fontSize: '12',
        fontWeight: 'bold',
        cursor: 'default',
        fill: '#35373e'
      },
      hover: {
        cursor: 'pointer'
      }
    },
    series: {
      markers: [
        // You can add one or more objects to create series for markers.
      ]
      regions: [
        // You can add one or more objects to create series for regions.
      ]
    },
    // map visualization is used to analyze and display the geographically related data and present it in the form of maps.
    visualizeData: {
      scale: ['#eeeeee', '#999999'],
      values: {
        EG: 29,
        US: 100,
        CA: 190,
        BR: 75,
        // ...
      }
    }
})

5. Add markers to the map on page load.

var markers = [
    {
      name: 'Palestine',
      coords: [31.5, 34.8],
    },
    {
      name: 'Russia',
      coords: [61, 105],
    },
    {
      name: 'Geenland',
      coords: [72, -42],
    },
    {
      name: 'Canada',
      coords: [56, -106],
    },
];
var map = new JsVectorMap({
    map: 'world',
    selector: '#map',
    regionsSelectable: true,
    markersSelectable: true,
    labels: {
      markers: {
        render: function (index) {
          return markers[index].name
        }
      }
    },
    markers: markers
})

// or
map.addMarker('RU', {
  name: 'Russia',
  coords: [61, 105],
  label: 'Russia',
  offset: [15, 10]
})

7. API methods.

// get selected regions
map.getSelectedRegions();
// clear selected regions
map.clearSelectedRegions();
// add markers
map.addMarkers([{
  name: 'Russia',
  coords: [61, 105]
}, {
  name: 'Egypt',
  coords: [26.8206, 30.8025],
  // Add some style for this particular marker.
  style: { fill: 'red' }
}])
// get selected markers
map.getSelectedMarkers();
// clear selected markers
map.clearSelectedMarkers();
// remove markers
map.removeMarkers()
// or
map.removeMarkers([1, 3])
// add lines
map.addLines([
  { from: 'United States', to: 'Egypt' },
  { from: 'Palestine', to: 'Ukraine' },
])
// remove lines
map.removeLines()
// OR
map.removeLines([{ from: 'United States', to: 'Egypt' }])
// update the size of the map
map.updateSize();
// set background color
map.setBackgroundColor('#ff0000');
// add a new method
map.extend('$hello', function (options) {
  const map = this
  // Do some logic...
})
map.$hello({});
// reset the map
map.reset();
// destroy the map
map.destroy();

8. Event handlers.

var map = new JsVectorMap({
    onLoaded: function (map) {
      window.addEventListener('resize', () => {
        map.updateSize()
      })
    },
    onViewportChange: function(scale, transX, transY) {
      // Do something
    },
    onRegionClick: function(event, code) {
      // Do something
    },
    onMarkerClick: function(event, markerIndex) {
      // Do something
    }
    onRegionSelected: function (index, isSelected, selectedRegions) {
      console.log(index, isSelected, selectedRegions);
    },
    onMarkerSelected: function (code, isSelected, selectedMarkers) {
      console.log(code, isSelected, selectedMarkers)
    },
    onRegionTooltipShow: function (tooltip, code) {
      if (code === 'RU') {
        tooltip.selector.innerHTML = tooltip.text() + ' <b>(Hello Russia)</b>'
      }
    },
    onMarkerTooltipShow: function (tooltip, index) {
      tooltip.selector.innerHTML = '<h5 class="mb-0">'+tooltip.text()+'</h5>' + '<p class="mb-0">Lorem ipsum dolor sit amet consectetur adipisicing elit.</p><small class="mb-0">Lorem ipsum dolor sit amet consectetur adipisicing elit.</small>'
    },
})

Changelog:

v1.7.0 (06/12/2024)

• feat(maps): add Brazil map
• feat: add setSelectedMarkers and fix element events
• refactor: rename jsvectormap.js to jsvectormap.esm.js
• refactor: drop class definition comment from classes
• feat(lines): add curved lines with curvature option
• fix(lines): programmatic creation of lines fails
• refactor: enhance marker and line components
• refactor: replace deprecated pageY/XOffset with scrollY/X
• chore: replace class with id
• fix: hide tooltip via prevent default
• feat: support ability to customize zoom buttons
• fix: panning to scroll on mobile devices #171
• refactor: missing using zoomInOption variable
• fix: tooltip might be undefined see
• refactor: use css variables to override style
• fix(tooltip): internal text overrides text from listeners
• revert: revert old lineStyle config to maintain compatibility
• fix(lines): curves distorted when it’s zero value
• refactor: enhance style and drop unwanted props

v1.6.0 (06/12/2024)

• feat(maps): create the build maps script
• feat(regions): set/clear selected regions programmatically
• fix(markers): add markers method
• chore: drop internet explorer entirly
• fix(visualization): NAN value is encountered when min and max are the same
• feat: allow all styles in add markers
• feat: refactor: support umd, es and cjs format

v1.5.2 (04/07/2023)

• fix(markers): get/clear selected markers
• fix: series doesn’t receive markers nor regions
• fix(events): tooltip fails when it’s disabled
• perf: massively improves performance when not using labels
• style: replace let with const for the sake of consistency
• refactor: abstract the zoom handlers
• style: replace let with const
• style: imporve variable declaration
• fix: zoom on mobile
• refactor: replace jsvectormap.js with index.js

v1.5.1 (08/16/2022)

• refactor: improve consistency & readbility

v1.5.0 (07/10/2022)

• feat(events): onRegion/MarkerClick support
• fix: shaky click selects a region
• fix: lines reposition fails
• refactor: improve the destroy method
• refactor: build an abstract class for components
• refactor: improve consistency & remove addMarker entirely
• feat: ability to remove a line or multiple lines
• refactor: better name conventions
• refactor: move elements to components
• refactor: get selector from merged options directly
• fix: too much recursion error
• feat(lines): ability to remove lines
• fix(typo): ‘tranparent’ typo in default options

v1.4.4 (02/09/2022)

• fix: lines position fail when zooming in/out

v1.4.3 (02/01/2022)

• refactor: switch addMap, maps, defaults to static
• revert: revert tooltip’s css method
• fix: touch handlers
• chore: cleaning up
• fix: marker’s render function

v1.4.2 (11/21/2021)

• fix: tooltip not destroyed

v1.4.0 (11/21/2021)

• refactor: drop dom handler class
• refactor: move tooltip functionality to class
• fix: fix mouseup event & fix zoom buttons
• refactor: clean up util API
• refactor: refactor directory structure
• fix: fix ‘addMarkers’ method doesn’t work with arrays
• fix(scroll): fix mouse wheel behavior

v1.3.3 (09/02/2021)

• fix: dragging the map selects the region
• fix: eventHandler’s off method doesn’t delete the reference
• style: correct events names for consistency
• feat: introduce a new event ‘onDestroyed’
• fix(add-markers): add markers method not working with object

v1.3.1 (06/16/2021)

• Update

v1.3.0 (01/18/2021)

• Deep refactor for jsvectormap that improves code structure and removing some unwanted code blocks
• Implement data visualization feature
• Ability to animate lines

v1.2.0 (12/29/2020)

• Add support for drawing lines between markers
• Fix simple issue with line class
• Feat(add-line): ability to create lines after map initialization.

v1.2.0 (12/29/2020)

• feat(destroy): added destroy method