Skip to main content

World Map

Preview

A canvas-rendered world map that plots points by longitude and latitude on the Robinson projection. Compose one WorldMap.Point per series inside WorldMap.Root, and size points by a count with sizeKey when many share one place.

When to use

  • Show where things are in the world: agents, endpoints, or edge locations placed by longitude and latitude.
  • Show one request on its detail page: zoom to the region of the client, keep a callout over its place, and draw a connector to the ngrok edge that received it.
  • Prefer Scatter Plot when the two values are measures, not a place on Earth.
  • Prefer Data Table when a reader needs to sort, filter, or act on each place more than see where it is.

Series

Each WorldMap.Point is one series, and it reads its latitudes from its own key. To split points by status, give each row its latitude under the key of its status and null under the others. A status that means good or bad takes a functional color and its own shape, so a reader can tell it apart without color vision. Compose WorldMap.Legend on every map with more than one series.

Zoom to a region

Set bounds to show one region, such as the area around a client. The region fills the plot and keeps its shape, so the plot shows more of the map on its loose side. Points outside the plot don't show, and the keyboard cursor skips them. The map ends at the antimeridian, so a region that reaches past ±180° stops there. The map has no wheel zoom and no pan: a detail card that takes the wheel traps the page scroll.

Callouts

WorldMap.Callout keeps a card over one place without a hover, such as the client location on a request's detail page. It is real DOM after the plot, so a screen reader reads it as page content. It shows once the map has painted, flips to the other side of its point when its own side has no room, moves to stay inside the plot near an edge, and hides while its place is outside the plot. When its content changes size, the map places it again. Set side="bottom" to put it below the point.

Connectors

WorldMap.Connector draws a line between two places, such as from a client to the ngrok edge that received its request. The line follows the great circle, the shortest route on the globe, and paints under the points. A connector is decoration: name both places with points and a legend, or with a callout, so a reader who cannot see the line gets the same facts.

Live data

Pass new rows whenever they arrive. A point at a place its series didn't have gets one ring, so a reader sees where the change happened. The ring starts at the point's edge, grows, and fades in 900ms. A point that moves is a new place: it doesn't glide across the map. A point that changes series at one place, such as an agent that goes offline, gets a ring too.

The map plays no ring:

  • under reduced motion, or with animate={false}
  • while it's off screen
  • for its first rows
  • for an update that adds more than 48 places
  • when it has more than 5,000 rows

At most 48 rings run at one time.

A map that updates on its own needs a control that stops the updates (WCAG 2.2.2), unless the reader started them.

Composition

Compose the parts of a WorldMap together to build your own:

WorldMap.Root├── WorldMap.Graticule├── WorldMap.Point (one per series)├── WorldMap.Connector├── WorldMap.Callout├── WorldMap.Tooltip└── WorldMap.Legend

Polymorphism

WorldMap.Callout accepts asChild. Use it to render your own element, such as a link to the client's details, in place of the default <div>. The map still places the element and merges its class names. The callout takes no pointer events, so a link needs pointer-events-auto in its className.

The projection

The map uses Arthur Robinson's projection (1963), from the table in Snyder and Voxland's An Album of Map Projections (USGS Professional Paper 1453, 1989). The interpolation is the one that d3-geo-projection's geoRobinson uses. Robinson is a compromise projection: it keeps neither area nor angles exact, and it keeps the distortion of both low across the whole map. The land is the Natural Earth 110m outline (public domain), about 8 KB gzipped, so the map needs no network request and no tile server. Only WorldMap loads the projection and the land: the other charts do not ship them.

The rationale and the alternatives considered (Equal Earth, a dotted land grid, clustering, spatial keyboard navigation) are in the repo's decision doc, decisions/2026-11-03-world-map.md.

Accessibility

Every interactive map must have an accessible name: an aria-label, or an aria-labelledby reference to a visible title. Omitting both is a compile error. The name lands on the focusable overlay. The canvas is hidden from assistive technology, so the map is never announced twice.

The map is one tab stop with a keyboard point cursor. Points are in order from west to east, which is the order of the data table too. The cursor skips a row that has no point in the plot. Such a row has no latitude in any series, or, with bounds, its point is outside the plot. The data table still lists a point outside the plot.

KeyBehavior
TabFocus the map: one tab stop regardless of point count.
ArrowLeft / ArrowRightStep to the next point to the west or to the east.
PageUp / PageDownJump forward or backward by 10% of the points.
Home / EndJump to the westernmost or easternmost point.
Enter / SpaceActivate the current point: fires onDatumActivate.
EscapeDismiss the readout.

Each step announces the point through a debounced polite live region: its name from labelKey, its coordinates, its series, and, with sizeKey, its size value. For example: "Frankfurt, 50.1° N, 8.7° E. Agents, agents: 21". Without labelKey, the coordinates are the name.

The overlay's aria-describedby points at a screen-reader description, data-slot="world-map-description": "World map with 13 points.", the series labels, and the keyboard instructions.

Once focus lands inside the map, it mounts a screen-reader data table with one row per point: its name, its series, its latitude, its longitude, and, with sizeKey, its size value in a column named by the key, bounded to the first 150 points from west to east. Value cells carry the raw number in data-value, so an agent can read exact coordinates from the DOM.

API Reference

WorldMap.Point, WorldMap.Graticule, and WorldMap.Connector are renderless: they register configuration with the Root, which paints everything on canvas. They accept no className and no DOM props. WorldMap.Callout, WorldMap.Tooltip, and WorldMap.Legend are the parts that touch real DOM, and each accepts div props.

WorldMap.Root

The root of a world map: owns the data, the Robinson projection, the canvas renderer, and the whole interaction contract. Renders a <div> wrapper with a 2:1 aspect ratio (override it with className) that holds the canvas, the focusable overlay, the sr-only description, the hover layers, the live region, and, once focus lands inside the map, the sr-only data table. The world, or the bounds region, sits centered in the plot at its own aspect ratio. Hovering hits the nearest visible point within 24px. With sizeKey, a pointer over a point hits the top point there, not a neighbor with a nearer center. Of two points at one place, hovering hits the one painted on top.

All props from div, plus:

PropTypeDefaultDescription
datareadonly TDatum[]Rows of data; each row is one point per composed WorldMap.Point series.
longitudeKeyExtract<keyof TDatum, string>The key of each row's longitude, in degrees east (−180 to 180). Rows without a finite longitude are not plotted. If no row has the key, the Root throws.
labelKey?Extract<keyof TDatum, string>The key of each row's name. The tooltip, the keyboard announcement, and the data table read it. A row without a name reads as its coordinates.
sizeKey?Extract<keyof TDatum, string>The key of each row's size value. A point's area follows the value: the largest value gets a 16px radius, and no point shrinks below 4px. Larger points paint first, across all series. The tooltip, the announcement, and the data table give the value. If no row has the key, the Root throws.
bounds?{ west: number; south: number; east: number; north: number }the whole worldThe region the map shows, in degrees. The region fills the plot and keeps its shape. The map ends at the antimeridian, so a region that reaches past ±180° stops there. west must be less than east, or the Root throws.
aria-labelstringThe map's accessible name. Exactly one of aria-label or aria-labelledby is required, unless mode is "decorative", which forbids both.
aria-labelledbystringThe id of a visible element that names the map. Preferred over aria-label when the map sits under a heading.
mode?"interactive" | "static" | "decorative""interactive"How much of the contract the Root exposes, as on every mantle chart.
animate?booleantrueAnimate the reveal and the ring around a new point. prefers-reduced-motion always wins.
pending?booleanfalseHold the previous render at reduced opacity while fresh data loads.
activeIndex?number | nullControlled active datum index (null = none). Allowed only when mode is "interactive".
onActiveIndexChange?(index: number | null) => voidNotified when hover or the keyboard moves the active index. Allowed only when mode is "interactive".
onDatumActivate?(event: ChartDatumEvent) => voidNotified on a point click or tap, or Enter/Space on the focused map. The event carries { index, xValue, datum, dataKey }: xValue is the longitude, and dataKey names the series (null for keyboard activation).

CSS variables

CSS VariableDefaultDescription
--world-map-land-colorvar(--color-neutral-200)The land fill.
--world-map-ocean-colorvar(--color-neutral-50)The fill inside the world's outline.

Data attributes

Data AttributeValueDescription
data-slot"world-map"The Root wrapper, with any forwarded chain ahead of it.
data-slot"world-map-plot"The plot box. Every overlay layer positions against it.
data-slot"world-map-canvas"The <canvas> the map paints on. Always aria-hidden. Engine-owned: absent from server HTML and from a dormant map.
data-slot"world-map-crosshair"The vertical hairline; a world map never shows it. Engine-owned, interactive maps only.
data-slot"world-map-hover-band"The category highlight; a world map never shows it. Engine-owned, interactive maps only.
data-slot"world-map-markers"The container for the hover dot on the hit point. Engine-owned, interactive maps only.
data-slot"world-map-tooltip"The tooltip surface. The Root renders it on the first hover or keyboard step and keeps it.
data-slot"world-map-description"The sr-only description the overlay's aria-describedby points at: the point count, the series labels, and, on an interactive map, the keyboard instructions. Omitted when mode="decorative".
data-slot"world-map-data-table"The sr-only data table: one row for each of the first 150 points from west to east, with its name, series, latitude, longitude, and, with sizeKey, its size value. Mounts once focus lands inside the map and stays. Interactive maps only.
data-state"dormant" | "engaged"On the Root. Flips to "engaged" once focus lands inside the map, and never flips back. Interactive maps only.
data-slot"chart-active-point"The hover dot on the hit point, inside the markers layer. Also carries data-shape.
data-shape"circle" | "square" | "triangle" | "diamond" | "triangle-down" | "plus" | "cross" | "star"On the hover dot, naming the glyph its series wears: the shape it set, else the circle. The dot clips itself to that glyph, so target this only to restyle a dot.

The engine appends the crosshair, the hover band, and the markers layer on the first hover, keyboard step, or controlled activeIndex that names a row. They stay until the Root destroys the engine, such as when mode leaves "interactive".

WorldMap.Graticule

Meridians and parallels every 30°, painted on canvas under the land. Renderless, and it takes no props. Omit the part to omit the graticule.

WorldMap.Point

One point series. Renders nothing itself: it registers the series with the map, which paints its points on canvas with a 2px surface ring. Rendering degrades by total point count: past 5,000 the points lose the ring, and past 20,000 a map with no sizeKey paints 2×2 squares.

PropTypeDefaultDescription
latitudeKeystringThe row key this series reads its latitudes from, in degrees north (−90 to 90). Put the key in every row, with null for a row not in this series.
label?stringlatitudeKeyDisplay name for the legend, tooltip, and data table.
colorSeriesColorThe color the series paints: a mantle color name, such as "blue" or "danger", or any CSS color. Required.
shape?"circle" | "square" | "triangle" | "diamond" | "triangle-down" | "plus" | "cross" | "star""circle"The glyph this series' points wear, mirrored by the legend key and hover dot.

WorldMap.Connector

A great-circle line between two places, painted on canvas under the points. Renderless. Where the line crosses the antimeridian, it runs to the edge of the map and starts again at the opposite edge.

PropTypeDefaultDescription
from{ longitude: number; latitude: number }The place the line starts, in degrees.
to{ longitude: number; latitude: number }The place the line ends, in degrees.
color?SeriesColor"neutral"The line color: a mantle color name or any CSS color.
lineStyle?"dashed" | "solid""dashed"Whether the line is dashed or solid.

WorldMap.Callout

A card that stays over one place, with no hover. It renders after the plot and takes no pointer events; add pointer-events-auto to className for a callout with a link. It stays hidden until the map paints, and while its place is outside the plot. When its content changes size, the map places it again.

All props from div, plus:

PropTypeDefaultDescription
longitudenumberThe place's longitude, in degrees east.
latitudenumberThe place's latitude, in degrees north.
side?"top" | "bottom""top"Which side of the place the callout sits on. It flips when that side has no room.
asChild?booleanfalseRender your own element in place of the <div>.
childrenReactNodeThe callout content.

Data attributes

Data AttributeValueDescription
data-slot"world-map-callout"The callout, with any forwarded chain ahead of it.
data-side"top" | "bottom"The side of the place the callout sits on after placement: side, or the other side after a flip.

WorldMap.Tooltip

Customizes the hover and keyboard readout. The tooltip renders even when this part is absent. The default readout names the point, then its coordinates, its size value with sizeKey, and its series.

All props from div, except children, plus:

PropTypeDefaultDescription
indicator?"dot" | "none""dot"The series color key beside each series name.
footer?ReactNode | ((snapshot: HoverSnapshot) => ReactNode)Content below the series rows.
children?(snapshot: HoverSnapshot) => ReactNodeReplace the whole readout. The snapshot carries the hovered row as datum.

Data attributes

Data AttributeValueDescription
data-slot"world-map-tooltip-label"On the display: contents <div> wrapping a children readout. The default readout has none.

WorldMap.Legend

Series names keyed by their point glyphs, rendered as real DOM in flow below the map. It renders nothing for a single series.

All props from div, except children, plus:

PropTypeDefaultDescription
children?(series: SeriesMeta[]) => ReactNodeReplace the default legend items; receives the registered series.

Data attributes

Data AttributeValueDescription
data-slot"world-map-legend"The legend list.
data-slot"world-map-legend-label"On the display: contents <div> wrapping a children render prop.
data-shape"circle" | "square" | "triangle" | "diamond" | "triangle-down" | "plus" | "cross" | "star"On each series' swatch, naming the glyph its WorldMap.Point wears.