@gramex/cartogram
v2.0.3
Published
A layered map visual that renders choropleths and cartograms from TopoJSON files
Downloads
37
Maintainers
Readme
@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 keyslayers
: 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 objectid
: 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 projectionwidth
: 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.
Resize features
Add an update
function to set any attribute on features based on data.
Animate features
Use .transition()
on in update
to animate the map.
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.
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.
Zoom to fit
By default, cartogram zooms to fit all layers. To zoom to specific layers, add fit: true
to the layers.
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).
Add tooltips
This example shows how to use Bootstrap tooltips.
- Add a
data-bs-toggle="tooltip" title="..."
attribute to each feature usingupdate
- Call
new bootstrap.Tooltip(element, {selector: '[data-bs-toggle="tooltip"]'})
to initialize tooltips
Change projection
This example shows how to pass a d3-geo projection as projection
.
Transform SVG
cartogram()
works on any <svg>
or <g>
element, and respects all transformations.
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 ofcartogram.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 [email protected]