Geo map

A React component in Beamline's Charts & data-vis category.

Values by country as a choropleth on the system's own world outline (no map service): classes from a sequential or diverging ramp with a legend you can point at to light one class, sized points for places, a ranked list beside it that previews and pins a country, a click that zooms to it, and countries never measured hatched; the outline loads only when a map is on screen.

Use it for

A measure that differs by country: revenue, signups, latency, share of traffic, growth against last period (diverging).
A few places that matter on a world view: data centres, offices, warehouses (points).

Not for

Exact comparison between a few countries (bar-list or bar-chart).
Street-level maps, routes or tiles (a map library with a tile service).
Markets by sector and change (market-heatmap).

Anatomy

chart frame: title, description, table button (every value as a table)
map: countries filled by class, hairline borders in the card's colour, hatched where not measured, points sized by value
legend: one swatch per class with its range, “Not measured”; pointing at a class lights its countries
ranked list beside or under the map: the top countries with value and share
zoom controls: zoom in, out, reset; a pinned country is zoomed to

Variants

0: ramp: cool (sequential, default) · heat · delta (diverging around `center`)
1: classes: 3–7 (default 5); scale: quantile (default: each class about as many regions, bounds rounded) · equal (round equal steps); delta always splits evenly around its centre
2: points: { lon, lat, value, label }
3: shapes: your own outline in the same shape as the world's (regions of a country, floors of a building)

States

loading (the outline arriving, or your data)
empty
not measured (null: hatched)
outside the data (no entry: the base fill)
previewed (pointing at a country, a list row or a legend class: the rest fade toward the card)
pinned (aria-pressed in the list; the map zooms to it)
zoomed
table view

Keyboard

Tab moves through the ranked list (Enter pins a country and zooms to it, Escape unpins), the legend classes, and the zoom buttons
The map itself is a picture; the table view and the list carry every number

Motion

Countries take their colour in a sweep from west to east on first draw. A new value glides its country's colour to its new class. Pinning eases the view to the country's bounds; reset eases back. Pointing fades other countries toward the card colour at once. Reduced motion places everything at once; nothing runs at rest.

Props

Prop	Type	Default	Description
`data` (required)	`GeoDatum[]`	—	{ id, value: number \| null, label? } by ISO 3166 alpha-2 code (or your shapes' ids).
`points`	`GeoPoint[]`	—	{ id, lon, lat, value, label } drawn as circles sized by value.
`ramp`	`"cool" \| "heat" \| "delta"`	—	Default cool; delta diverges around `center`.
`center`	`number`	—	Diverging midpoint. Default 0.
`scale`	`"quantile" \| "equal"`	—	How sequential classes are cut. Default quantile.
`classes`	`number`	—	How many colour classes. Default 5.
`format`	`(value: number) => string`	—	How values read.
`list`	`boolean \| number`	—	The ranked list; a number caps its rows. Default 8.
`zoomable`	`boolean`	—	Zoom controls and zoom to a pinned country. Default true.
`active / defaultActive / onActiveChange`	`string \| null`	—	The pinned country's id.
`shapes`	`{ width, height, shapes: GeoShape[] }`	—	Your own outline instead of the world.
`title / hideTitle / description / table / loading / emptyLabel / actions`	`…`	—	The chart frame every chart shares.
`className / classNames / style / ref`	`string / ChartClassNames / CSSProperties / Ref<HTMLElement>`	—	The chart figure and its frame parts.

Dependencies

lucide-react

Import

import { GeoMap } from "@/components/geo-map/geo-map";

Get it

Geo map is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent