Map

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.

Map charts combine two ingredients:

1. Geographic shapes — the borders of regions (GeoJSON or TopoJSON).
2. 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/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.

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:

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: '#00aaff' },
    { id: '276', label: 'Germany', color: '#00aaff' },
    { 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:

The chart automatically fits the projection to the loaded features using fitExtent, so you normally do not need to set scale or center manually.

Coloring

Regions are colored in three ways, in order of priority:

1. Per-item color — explicit CSS color on a data item.
2. matchFill — applied to matched regions without their own color.
3. 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.

Default colors used by the chart come from the RareCharts theme. They are defined in: /src/core/theme.js. The map section of the theme defines values such as matchFill, unmatchedFill, border, and hover behavior. In most cases it is better to adjust those defaults in the theme rather than overriding colors in every chart instance.

Tooltip

The default tooltip shows the region name and, if present, the value for every region on the map, including regions with no matching data item.

If you need something more specific, override it:

tooltipFormat: ({ feature, item }) => `
    <strong>${item?.label ?? feature.properties.name}</strong>
    <div>Revenue: $${item?.value?.toLocaleString()}</div>
`

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.

Map chart options

Common options shared by all chart types (title, subtitle, source, theme) are documented on the Settings page.

Data fields

Minimal example

new RareCharts.Map('#chart', {
    title:      'Market Presence',
    topoUrl:    '/assets/charts/data/countries-110m.json',
    topoObject: 'countries',
    height:     400,
    matchFill:  '#00aaff',
    zoom:       true,
}).setData([
    { id: '840', label: 'United States' },
    { id: '276', label: 'Germany'       },
    { id: '392', label: 'Japan'         },
]);

In practice the workflow is usually straightforward:

1. Load a geographic file, usually TopoJSON.
2. Match your data to regions by ID.
3. Decide which regions should be highlighted.
4. 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.