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:
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.
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:
CSS variables
Data attributes
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.
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.
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:
Data attributes
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:
Data attributes
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:
Data attributes