Maps

Highcharts Maps is a module away: the map series renders TopoJSON geometries, mappoint places lat/lon markers, mapline draws routes and flowmap animates flows between coordinates. Geometry data loads from the Highcharts map collection (a same-origin copy is vendored at /mapdata/world.topo.json).

Module setup. Registers map/mapline/mappoint/flowmap series. Map geometries are TopoJSON — the site vendors world.topo.json at /mapdata/; any TopoJSON you host works the same way. See the snippets.

import "highcharts/modules/map";

Usage

Create a chart atom with standard Highcharts options, then render Chart(chart) anywhere in a mates template. Every later chart.set(…) or chart.update(…) re-renders the chart — no imperative Highcharts code.

Quick start

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "map"
    },
    title: {
        text: "Renewable energy share"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: true
    },
    colorAxis: {
        min: 0,
        max: 100,
        stops: [
            [
                0,
                "#e6f7f5"
            ],
            [
                0.5,
                "#4db6ac"
            ],
            [
                1,
                "#00695c"
            ]
        ]
    },
    series: []
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Live examples

World choropleth Highcharts demo ↗

Countries join on their hc-key; the colorAxis ramp shades values. Map geometry loads asynchronously and is fed to the atom via update().

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";
import "highcharts/modules/map";

const chart = chartAtom({
    chart: { type: "map" },
    title: { text: "Renewable energy share" },
    colorAxis: { min: 0, max: 100, stops: [[0, "#e6f7f5"], [0.5, "#4db6ac"], [1, "#00695c"]] },
    legend: { enabled: true },
    series: [], // filled once the geometry loads
});

fetch("/mapdata/world.topo.json")
    .then((r) => r.json())
    .then((topo) => {
        chart.update({
            series: [{
                type: "map",
                mapData: topo,
                joinBy: ["hc-key", "code"],
                data: [{ code: "no", value: 71 }, { code: "br", value: 82 }, /* … */],
            }],
        });
    });

export const MyChart = () => html`<div style="height: 30rem">${Chart(chart)}</div>`;

Map points (cities by population) Highcharts demo ↗

mappoint places markers by latitude/longitude — no geometry needed. Marker size encodes z with the bubble-like sizing options.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";
import "highcharts/modules/map";

const chart = chartAtom({
    chart: { type: "map" },
    title: { text: "Major cities" },
    series: [],
});

fetch("/mapdata/world.topo.json")
    .then((r) => r.json())
    .then((topo) => {
        chart.update({
            series: [{
                type: "map", mapData: topo, name: "World",
                borderWidth: 0.3, borderColor: "#94a3b8", enableMouseTracking: false,
            }, {
                type: "mappoint",
                data: [
                    { name: "Tokyo", lat: 35.68, lon: 139.69, z: 37 },
                    { name: "Delhi", lat: 28.61, lon: 77.21, z: 32 },
                    // …
                ],
            }],
        });
    });

Orthographic globe Highcharts demo ↗

chart.projection swaps the projection — Orthographic renders a rotatable globe. Enable mapNavigation to drag and zoom it.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";
import "highcharts/modules/map";

const chart = chartAtom({
    chart: { type: "map", projection: { type: "Orthographic", rotation: [0, -15] } },
    title: { text: "The world as a globe" },
    mapNavigation: { enabled: true, enableButtons: true },
    series: [],
});

fetch("/mapdata/world.topo.json")
    .then((r) => r.json())
    .then((topo) => chart.update({
        series: [{ type: "map", mapData: topo, name: "World", borderWidth: 0.4 }],
    }));

Flight routes (map lines) Highcharts demo ↗

mapline series draw LineString geometry between coordinates — the classic routes-over-continents view.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "map"
    },
    title: {
        text: "Routes from London"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    series: []
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Flow map (animated migration) Highcharts demo ↗

The flowmap series animates weighted flows between coordinate pairs — migration, trade or traffic, straight from the map module.

Module setup. This example needs 2 extra Highcharts modules:

import "highcharts/modules/map";
import "highcharts/modules/flowmap";

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "map"
    },
    title: {
        text: "Migration flows"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    series: []
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Options reference

mates-charts passes options straight through to Highcharts — these are the keys that matter for maps charts. See the full Highcharts API for everything else.

Option	Type	Default	Description
`chart.type`	"map" \| "mapline" \| "mappoint" \| "flowmap"	—	All registered by highcharts/modules/map (flowmap has its own module).
`series[].mapData`	TopoJSON \| GeoJSON	—	Geometry — load from https://code.highcharts.com/mapdata/.
`series[].joinBy`	[mapKey, dataKey]	["hc-key", "hc-key"]	How data rows join to geometry.
`colorAxis.stops`	[stop, color][]	—	Choropleth value ramp.
`chart.projection`	{ type, rotation }	EqualEarth	Orthographic renders a rotatable globe.
`mapNavigation.enabled`	boolean	false	Pan/zoom controls for maps.
`series[].data[].lat / lon`	number	—	mappoint/flowmap positioning.