Click a visited country.
The Map chart renders geographic data as a choropleth or region-highlight map. In practice this usually means one simple thing: you have data tied to places and you want to show it on a map.
Common examples include visited countries, regional performance, market presence, or anything else where geography matters more than a precise number. To draw flows between places — capital, goods, influence — use Map Flows.
Map charts combine two ingredients:
- Geographic shapes — the borders of regions (
GeoJSONorTopoJSON). - Value data — an array of items that match those regions by ID.
The map provides the geometry; your data decides what gets highlighted.
Geographic data
Pass a URL to fetch, or an inline object — whichever fits your pipeline.
// TopoJSON from a local file
new RareCharts.Map('#chart', {
topoUrl: '/assets/charts/data/maps/world/level-0/world-atlas/countries-110m.json',
topoObject: 'countries', // named object inside the topology
});
// GeoJSON fetched from a URL
new RareCharts.Map('#chart', {
geoUrl: '/data/europe.geojson',
});
// Inline GeoJSON FeatureCollection
new RareCharts.Map('#chart', {
geoData: myFeatureCollection,
});
RareCharts supports both GeoJSON and TopoJSON. Give one source; if several are set, the first of geoData, topoData, geoUrl, topoUrl is used.
A URL loads asynchronously. chart.whenReady() returns a promise that resolves to the chart once the geometry has loaded and the map is drawn. It also resolves when the file fails to load: the error goes to the console and the map stays empty. A map given no source at all draws nothing and warns in the console.
const chart = new RareCharts.Map('#chart', {
topoUrl: '/assets/charts/data/maps/world/level-0/world-atlas/countries-110m.json',
topoObject: 'countries',
}).setData([{ id: '250', label: 'France' }]);
chart.whenReady().then(() => {
// the regions are on the page now
});
In practice TopoJSON is usually the better choice for world maps: it is smaller, simpler to ship with your bundle, and avoids duplicated borders between neighboring regions.
Open geographic datasets
A convenient public source of world map data is the world-atlas dataset: https://cdn.jsdelivr.net/npm/world-atlas@2/.
It provides several ready-to-use TopoJSON files that differ only by geometric detail:
| File | Description |
|---|---|
countries-110m.json |
Smallest dataset. Best for dashboards and simple maps (~100 Kb) |
countries-50m.json |
Medium detail. Good default for most projects (~750 Kb) |
countries-10m.json |
High detail. Suitable for zoomable or full-screen maps (~3.5 Mb) |
Example:
new RareCharts.Map('#chart', {
topoUrl: 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-50m.json',
topoObject: 'countries'
});
These files use ISO 3166-1 numeric country codes as feature.id, which makes them easy to match with data items.
Value data
Each item in the data array identifies a geographic feature and optionally carries a value and color:
chart.setData([
{ id: '250', label: 'France', color: '#1677ff' },
{ id: '276', label: 'Germany', color: '#1677ff' },
{ id: '380', label: 'Italy', value: 42 },
]);
The id field must match either feature.id or a property inside feature.properties.
For example:
- world-atlas TopoJSON uses numeric ISO 3166-1 country codes as
feature.id - other datasets often store identifiers inside
feature.properties
If needed, use the idField option to tell the chart which property should be used.
Projections
RareCharts supports five projections:
| Name | Description |
|---|---|
'naturalEarth1' |
Default. Balanced projection suitable for most maps |
'mercator' |
Familiar web-map projection. Often used for regional maps |
'equalEarth' |
Equal-area projection. Useful when region size matters |
'orthographic' |
Globe view. Mostly for visual context |
'identity' |
No geographic projection. Useful when your GeoJSON is already in screen coordinates or a custom planar space |
The chart automatically fits the projection to the loaded features using fitExtent, so you normally do not need to set scale or center manually.
graticule: true draws a 10° grid of meridians and parallels under the regions, in theme.map.graticule — it shows over the sea and wherever no region covers it. With projection: 'identity' there is none: planar data has no meridians.
Coloring
Regions are colored in three ways, in order of priority:
- Per-item
color— explicit CSS color on a data item. matchFill— applied to matched regions without their own color.defaultFill— applied to regions that have no matching data.
For a simple highlight map (visited countries, market presence), a single matchFill is usually enough.
For a choropleth map, you will typically compute colors yourself using a scale and pass them through the color field.
Hovering a region with data lightens it: its fill moves theme.map.hoverBrighten − 1 of the way towards white (1.3, so 30%; dark 1.2) — black lightens too and nothing turns pure white, while a fill already very light (lightness above 0.85) darkens a little instead, so each color of a choropleth gets its own lighter shade. Set hoverFill for one fixed hover color instead, or hoverBrighten: 1 in the theme to turn the effect off. Regions without data do not react.
Default colors come from the theme's map section — RareCharts.defaultTheme.map and RareCharts.darkTheme.map: matchFill (null: the accent, #1677ff; dark #ff6200), unmatchedFill (#e8e8e8, or the page's --chart-grid-color; dark #1e1e2e), border (#ffffff, or the page's --chart-bg; dark #444455), ocean (transparent), hoverBrighten (1.3; dark 1.2) and graticule (null: the text at 8%; dark rgba(255,255,255,0.06)). With matchFill left null, changing accent recolors a map too. In most cases it is better to set them once in the theme — createTheme({ map: { matchFill: '#fa8c16' } }) — than in every chart instance.
Tooltip
The default tooltip shows a region with a value as a row — a dot in its fill, its name and the value — and a region without one by its name, for every region on the map, including regions with no matching data item.
If you need something more specific, override it:
tooltipFormat: ({ label, value, color }) => `
<div class="rc-tooltip-row">
<span class="rc-tooltip-swatch rc-tooltip-swatch--dot" style="--rc-swatch-color:${color}"></span>
<span class="rc-tooltip-label">${label}</span>
<span class="rc-tooltip-value rc-num">${value == null ? '—' : '$' + value.toLocaleString()}</span>
</div>
`
The classes are the default tooltip's rows: Custom tooltip lists them.
The formatter receives both the raw feature and the matched item, so you can display whatever makes sense. For unmatched regions, item will be null. It also gets the role fields every formatter gets: label (the name the default tooltip shows), value (item.value, or null) and color (the region’s fill).
Region clicks
onRegionClick tells your page which region was clicked; the chart does not navigate by itself.
new RareCharts.Map('#map', {
onRegionClick: ({ item, label }) => {
if (!item) return showDefault(); // the sea, a region without data, Escape
location.href = `/countries/${item.slug}/`; // your own field on the data item
},
});
Only regions with a data item take part: they show a pointer, can be reached with Tab and pressed with Enter or Space, and each is named for screen readers by its label and value. A click anywhere else on the map — the sea, a region without data — and Escape on a focused region report item: null, so the page can go back to what it showed before anything was chosen; feature is then the region without data, or null. A drag that pans or zooms the map is not taken for a click, and on MapFlow a click on an arc or a place reports nothing. In the map at the top of this page, click a visited country, then the sea.
Map chart options
Common options shared by all chart types (title, subtitle, source, note, controls, theme) are documented on the Settings page. The legend is a caption here: the chart has no series to hide.
| Option | Type | Default | Description |
|---|---|---|---|
Layout |
|||
height |
number | 400 |
Container height in px. Width is always 100% of the container. |
fitPadding |
number | 20 |
Padding in px around the feature bounds when fitting the projection. |
Geographic data |
|||
geoUrl |
string | — | URL of a GeoJSON FeatureCollection to fetch via d3.json(). |
geoData |
object | — | Inline GeoJSON FeatureCollection or single Feature. |
topoUrl |
string | — | URL of a TopoJSON topology to fetch. |
topoData |
object | — | Inline TopoJSON topology object. |
topoObject |
string | first object |
Named object inside the topology to extract. Defaults to the first key in topology.objects.
|
featureFilter |
function | — | Optional filter applied to extracted features before rendering. Receives feature and should return true to keep it. |
clipExtent |
[[lon, lat], [lon, lat]] |
— | Geographic bounding box used to keep only polygons intersecting that extent. |
idField |
string | 'id' |
Feature property used as ID when feature.id is absent.Falls back through iso_a2, iso_a3, ISO_A2, ISO_A3 automatically.
|
Projection |
|||
projection |
'naturalEarth1' | 'mercator' | 'equalEarth' | 'orthographic' | 'identity' |
'naturalEarth1' |
D3 geo projection to use for rendering. |
reflectY |
boolean | false |
Flip the Y axis. Only applies with projection: 'identity' — planar source data often uses a Y axis that grows downward. |
rotate |
array | — | Optional projection rotation passed to projection.rotate([lambda, phi, gamma]) when supported by the chosen projection. |
graticule |
boolean | false |
Draw a 10° grid of meridians and parallels under the regions, in theme.map.graticule (rgba(0,0,0,0.08); dark rgba(255,255,255,0.06)). Not drawn with projection: 'identity'. |
Colors |
|||
defaultFill |
CSS color | theme.map.unmatchedFill (#e8e8e8; dark #1e1e2e) |
Fill for regions with no matching data item. |
matchFill |
CSS color | theme.map.matchFill (null: the accent, #1677ff; dark #ff6200) |
Fill for matched regions that have no explicit color field. |
hoverFill |
CSS color | auto | Fill of a region with data under the pointer — its own color included; regions without data keep theirs. Default: the region's own fill moved theme.map.hoverBrighten − 1 of the way towards white (1.3; dark 1.2; 1 turns the effect off); a very light fill darkens a little instead. |
oceanColor |
CSS color | 'transparent' |
SVG background fill (the "ocean" behind land features). Transparent by default (theme.map.ocean, light and dark), so the card's background shows through. |
borderColor |
CSS color | theme.map.border (#ffffff; dark #444455) |
Stroke color for feature borders. |
borderWidth |
number | 0.5 |
Border stroke-width in px. |
Interaction |
|||
zoom |
boolean | false |
Zoom and pan: Ctrl/⌘ + wheel or a trackpad pinch zooms, a drag pans; on a phone two fingers pan and pinch. A plain wheel or one finger scrolls the page, with a short hint over the map. |
zoomExtent |
array | [0.8, 12] |
Minimum and maximum zoom scale used when zoom is enabled. |
tooltipFormat |
function | built-in | ({ feature, item, label, value, color }) => html — custom tooltip for any region. item is null when no data item matches; label is the name the default tooltip shows (item.label, then the feature’s name or id), value is item.value (null without an item), color the region’s fill (formatter arguments). |
onRegionClick |
function | — | ({ feature, item, label, value, event }) => void — a click, Enter or Space on a region with a data item. The chart only reports it; your page decides what happens. With a handler those regions show a pointer, take keyboard focus and get the focus ring. A drag that pans the map is not a click. See Region clicks. |
Data fields
| Field | Type | Description |
|---|---|---|
id |
string | number | Required. Must match feature.id or the resolved idField property. |
label |
string | Display name used in the tooltip. Falls back to feature.properties.name. |
value |
number | Optional numeric value. Shown in the default tooltip; available in tooltipFormat. |
color |
CSS color | Explicit fill for this region. Overrides matchFill. |
Minimal example
new RareCharts.Map('#chart', {
title: 'Market Presence',
topoUrl: '/assets/charts/data/maps/world/level-0/world-atlas/countries-110m.json',
topoObject: 'countries',
height: 400,
matchFill: '#1677ff',
zoom: true,
}).setData([
{ id: '840', label: 'United States' },
{ id: '276', label: 'Germany' },
{ id: '392', label: 'Japan' },
]);
In practice the workflow is usually straightforward:
- Load a geographic file, usually TopoJSON.
- Match your data to regions by ID.
- Decide which regions should be highlighted.
- Leave the projection and fitting to the chart unless you have a specific reason not to.
For most use cases, that is enough. The difficult part is rarely drawing the map itself. It is usually getting the region IDs to line up, finding a geography file that does not look terrible, and resisting the temptation to turn a simple highlight map into a geopolitical event.