Jsvectormap: jVectorMap without jQuery, for choropleth dashboards

Why the fork exists: dropping jQuery

Jsvectormap describes itself as a lightweight JavaScript library for creating interactive maps and pretty data visualization, and the README gives the origin in one sentence: this project is a deeply modified version of jvectormap and was created to help developers who aren't using jQuery anymore in their projects.

That is the entire reason for the project, and it is worth understanding what that implies. jVectorMap is an old library built on jQuery, and jQuery is a dependency that a great many projects have since removed for good reasons. A fork that keeps the SVG rendering behaviour and the map data but drops the jQuery requirement is the cheapest path for anyone who liked jVectorMap's maps and did not want to adopt its framework.

The browser support claim is that Jsvectormap supports all modern browsers including IE9+. That IE9 mention is a leftover of the jVectorMap lineage rather than a target, and it tells you the fork is about compatibility with an existing codebase rather than about being current.

The library itself is published on npm as jsvectormap, with badges for the version, the monthly downloads, the jsDelivr package data and the Bundlephobia minified and minizipped size. The primary language is JavaScript, the licence is MIT, the default branch is main, and the recent releases are v1.7.0 from 2025-05-31, v1.6.0 from 2024-06-12 and v1.5.2 from 2023-04-07. The last push was on 2026-04-23, so the code has moved since the last published version.

The documentation is hosted separately at jvm-docs.vercel.app, with an introduction page, and the README links to both the docs and a live demo.

The quick start, and how a map file becomes a map

The usage path is short, and it is worth walking through because the structure tells you how the library is put together.

Installation is one npm command.

npm i jsvectormap

Then you import the library and the map data you want, and construct a map.

import jsVectorMap from 'jsvectormap'
import 'jsvectormap/dist/maps/world.js'

const map = new jsVectorMap({
  selector: '#map',
  map: 'world',
})

Two separate imports are doing two separate jobs. The first brings in the library, whose default export is the map constructor. The second imports the map data itself, and the name of that file is the value you pass to the map option. The world's regions arrive as a side effect of the import rather than as an argument, which is why the map option is a short name rather than a data object.

That pattern has a practical consequence worth knowing before you build. Map data is a separate artefact from the library, so a page that shows three maps imports three data files, and the bundle contains the geometry for all the regions in them. For a site with a world map plus a handful of country maps, that is a meaningful amount of path data shipped to the browser, and it is the main reason the library describes itself as lightweight only in the context of its jQuery-free competitors rather than in absolute terms.

The constructor takes a selector string rather than an element, so the map mounts into whatever the selector resolves to, and the map option names the imported data file.

The repository structure supports the same separation at build time. There is a packages/ directory under a pnpm workspace, along with docs/ and scripts/, and the root package.json is marked private with workspaces for docs and packages/*.

The workspace layout and the separate maps package

The root package.json is not the library's manifest. It is a private workspace root, and its scripts are all filtered commands that delegate into the sub-packages.

  "scripts": {
    "playground:dev": "pnpm run --filter=playground dev",
    "library:dev": "pnpm --filter=jsvectormap dev",
    "library:build": "pnpm --filter=jsvectormap build",
    "maps:build": "pnpm run --filter=jsvectormap-maps build",
    "docs:dev": "pnpm run --filter=docs dev"
  }

Five packages, five purposes. The library itself is jsvectormap, the map data is jsvectormap-maps, there is a playground for trying things out, a docs package for the documentation site and, by implication from the filter names, a workspace for the packages/ directory.

The build toolchain is Rollup with Babel and a set of plugins. The dev dependencies include the Babel environment preset, the Rollup Babel and node-resolve plugins, autoprefixer, babel-loader, glob, postcss, rollup-plugin-scss for the stylesheets, rollup-plugin-terser for minification, and sass itself. The versions are modern, with Babel 7.26, PostCSS 8.5, Rollup 2.79 and Sass 1.86.

Two of those choices matter for anyone extending the library. First, Rollup rather than webpack, which suits a library that ships ES modules and gets consumed by a bundler anyway. Second, the SCSS plugin and Sass dependency, which says the styles are authored as Sass and compiled as part of the build rather than shipped as prebuilt CSS, so the map container styles are part of the package.

The map data build is a separate target, which is consistent with the import pattern in the quick start. The world.js file you import in the quick start is a build product of the maps package, and the fact that it lives under dist/maps in the published package means the data ships alongside the library.

The playground exists as its own workspace package with its own dev script, which is the practical way to iterate on a map without a host application.

What an interactive map gives you, in the project's own terms

The README has a short section titled What's an interactive map, and its four points describe the feature set without much ornamentation.

An interactive map is a powerful tool for presentation. It gives the ability to create layers of information that can be shown or hidden at the click of a button on a region or maybe a marker. Data can be quickly updated, and these updates made transparent to users. Zoom functions allow users to focus on either the details of a particular region, or to gain a quick overview of a wider area.

Each of those four points maps onto a specific capability, and the layering point is the one that distinguishes this from a static choropleth image.

Showing and hiding information per region or per marker means the map is not one dataset painted onto a shape. It is a set of layers over a base map, and the user controls which ones are visible. For a dashboard where a reader wants to compare one metric and then another, that is the difference between reloading the page and clicking.

The transparency point about data updates is about the reading experience rather than the technical one. When the numbers change, the map changes, and the user can see that the map is showing current data rather than a cached image.

Zoom is the mechanism for scale. Focusing on a particular region means a user can go from a country view down to a district without the page navigating away.

What the list does not mention is worth noting as much as what it does. There is no mention of projection, of tile layers, of geocoding, of territory disputes or of geographic queries. The map data is a fixed set of named regions with paths, and the library's job is to colour, highlight, label and zoom them. That is a visualisation library with a map-shaped data source, not a mapping engine, and the distinction decides whether it fits your project.

Contributing, and what the build rules say

The Contributions section is brief, and the rule it states is the kind of thing that saves a reviewer time.

Your contributions are always welcome, but consider the following notes: the build files shouldn't be updated when sending pull requests.

That instruction exists because the build outputs are committed. The repository contains the packages/ directory with the library, and the distributed files are generated into the package, so a contributor who rebuilds everything as part of a change produces a large diff of generated artefacts that obscures the actual change. The instruction says to leave those files alone and let the maintainer regenerate them.

The project uses a pnpm workspace with pnpm-workspace.yaml and pnpm-lock.yaml, and the scripts/ directory holds the tooling that the root scripts call. The docs/ directory is the documentation package, and the site is deployed to Vercel, which is consistent with the jvm-docs.vercel.app hostname and the separate docs package in the workspace.

The .github/ directory holds the workflow and issue templates, and the repository also carries a .gitignore and a LICENSE file at the root alongside the README.

Two things are worth noting for someone evaluating the project as a dependency. The MIT licence is permissive, so vendoring the code into a commercial product is not a licensing question. And the fact that the build outputs are committed means you are consuming a snapshot that the maintainer regenerated, so an npm version and the git master branch can differ in ways that are not obvious from the version number.

Where Jsvectormap is the wrong choice

There are three limits, and the first is about the category of tool it belongs to.

The first is that this renders vector maps of predefined regions, and it does not do cartography. There is no projection system, no tile layer, no coordinate handling beyond what the SVG paths give you, and no way to ask what is at a given latitude and longitude. If your data is points on a globe, or if you want to draw your own boundaries, or if you need to show street-level detail, this is the wrong category of library and no amount of configuration will change that.

The second is the map data, and its size and granularity. The quick start imports a map file by name, and the regions in those files are the political units the data was drawn for. Whether a map includes a disputed territory as its own region, and how a particular administrative division is drawn, is a data question and a political question, and both are outside the library's scope. For a product whose users are in a specific country, you will need to check that the map package actually contains the subdivisions you intend to colour, at the level you intend to colour them, and that the region identifiers in the data match whatever your own data uses.

The third is that the fork inherits its parent's limits while carrying the cost of a fork. Jsvectormap is a deeply modified version of jvectormap, so the rendering model, the region identifiers and the overall API shape come from that project, and the modern parts are the build tooling and the removal of jQuery. If jVectorMap itself were maintained in a modernised form, that would be the better dependency. The npm ecosystem has more recent options, and some of them use canvas rather than SVG, which matters if you are animating or have many regions.

The honest alternative for the choropleth case is a mapping library that treats the map as a first-class concept. Leaflet with a GeoJSON layer, or MapLibre GL, give you real geographic data, pan and zoom over any projection, and plugins for the same choropleth use case, at the cost of a larger dependency and a rendering model you have to learn. If you want a dashboard where the map is one widget among several, the dedicated visualisation library is less code; if the map is the product, a mapping library is the right foundation.

What Jsvectormap gives you is the narrow thing that jVectorMap gave you, without the jQuery bill. That is a legitimate reason to choose it, and it is also a reason to know that you are choosing a visualisation widget rather than a mapping platform.

Editorial conclusion

Adopt Jsvectormap if you already know jVectorMap and want its SVG maps without pulling jQuery into a modern build, since the fork exists for exactly that reason. Do not adopt it if you want a mapping library with projections, tile layers or geographic queries, because it draws vector maps of predefined regions rather than doing cartography. Before you commit, check the map data package for the regions you need, and note the last push was on 2026-04-23 with release v1.7.0 from 2025-05-31.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. themustafaomar/jsvectormap on GitHub