@gramex/cartogram

A layered map visual that renders choropleths and cartograms from TopoJSON files.

Example

Given this TopoJSON file of Japan, you can render a map like this:

Here is the source code for the map above

Installation

Install via npm:

npm install @gramex/cartogram

Use locally as an ES module:

<script type="module">
  import { cartogram } from "./node_modules/@gramex/cartogram/index.js";
</script>

Use locally as a script:

<script src="./node_modules/@gramex/cartogram/cartogram.min.js"></script>
<script>
  gramex.cartogram(...)
</script>

Use via CDN as an ES Module:

<script type="module">
  import { cartogram } from "https://cdn.jsdelivr.net/npm/@gramex/cartogram@1/cartogram.js";
</script>

Use via CDN as a script:

<script src="https://cdn.jsdelivr.net/npm/@gramex/cartogram@1/cartogram.min.js"></script>
<script>
  gramex.cartogram(...)
</script>

API

The cartogram() function accepts the following parameters:

element: the SVG element to render the map in. This may be an <svg> or a <g> element.
options: an object with the following keys
- layers: an array of layers. Each layer draws a map. It's an object with these keys:
  - type: "choropleth", "cartogram" or "centroid"
  - data: a TopoJSON map object
  - id: optional ID for the map layer;
  - filter: optional function to filter which features are drawn, e.g. (d) => d.properties.population > 1000000
  - update: optional function to update the map features, e.g. (join) => join.attr('fill', d => d.color)
  - fit: optional boolean. If true, the projection automatically fits to the boundary of this layer
- projection: Any d3-geo projection
- width: optional width of the map. Defaults to the element's size (or the nearest SVG parent)
- height: optional width of the map. Defaults to the element's size (or the nearest SVG parent)

Color features

Add an update function to color features based on data.

Source code

Resize features

Add an update function to set any attribute on features based on data.

Source code

Animate features

Use .transition() on in update to animate the map.

Source code

Add shapes at centroid

The "centroid" layer type lets you add any shape to the map. This example adds a square and a label at the centroid of each feature.

Source code

Filter features

The filter function is called with each feature. Features are objects with the following keys:

type: "Feature"
properties: An object with the properties of the feature. This varies by map.
geometry: An object with the geometry of the feature. Use d3-geo to process this

This example draws 2 layers. The second layer filters selected features and colors it in red.

Source code

Zoom to fit

By default, cartogram zooms to fit all layers. To zoom to specific layers, add fit: true to the layers.

Source code

Multiple maps

You can add different maps in each layer. In this map, we have one layer for France (red) and one for Germany (green).

Source code

Add tooltips

This example shows how to use Bootstrap tooltips.

Add a data-bs-toggle="tooltip" title="..." attribute to each feature using update
Call new bootstrap.Tooltip(element, {selector: '[data-bs-toggle="tooltip"]'}) to initialize tooltips

Example

Source code

Change projection

This example shows how to pass a d3-geo projection as projection.

Source code

Transform SVG

cartogram() works on any <svg> or <g> element, and respects all transformations.

Source code

Documentation

Release notes

2.0.3: 18 Aug 2024. Security fix.
2.0.2: 1 Nov 2023. Include README.md in npm package. Lint code before publishing.
2.0.1: 31 Oct 2023. Re-license from AGPL 3.0 to MIT.
2.0.0: 16 Jun 2023. Build as gramex.cartogram() instead of cartogram.cartogram().
1.1.0: 8 Jun 2023. Add type="centroid". Support transitions. fit supports multiple layers.
1.0.1: 7 Jun 2023. Initial release

Authors

Anand S s.anand@gramener.com

License

MIT