# Geo map

A React component in [Beamline](https://beamline.io/)'s [Charts & data-vis](https://beamline.io/components/charts) category. Live demo: https://beamline.io/components/geo-map

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](https://beamline.io/components/bar-list) or [bar-chart](https://beamline.io/components/bar-chart)).
- Street-level maps, routes or tiles (a map library with a tile service).
- Markets by sector and change ([market-heatmap](https://beamline.io/components/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

```tsx
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](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Charts & data-vis

- [Sankey chart](https://beamline.io/components/sankey-chart): Flows between stages as bands whose width is the amount: sources to pages to outcomes, budgets to teams; hovering or focusing a node lights its flows and…
- [Streamgraph](https://beamline.io/components/streamgraph): Stacked flows over time around a centre baseline, with silhouette, wiggle, expand (shares) and zero offsets: a legend that turns layers on and off, a…
- [Ridgeline](https://beamline.io/components/ridgeline): Distributions per group as overlapping density ridges (response time by region, order size by plan): an overlap control, median and p95 readouts per row…
- [Treemap](https://beamline.io/components/treemap): Nested rectangles sized by value (spend by team, then service), squarified so tiles stay close to square: labels that fit or hide, hover and focus…
- [Gantt chart](https://beamline.io/components/gantt-chart): A plan as bars on a timeline: tasks grouped down the side, each bar from its start to its end with its progress, milestones as diamonds, arrows from each…
- [Activity heatmap](https://beamline.io/components/activity-heatmap): A calendar of daily counts, one cell per day on a sequential ramp: weeks across, weekdays down, month and weekday labels, a legend scale, hatched days…
- [Gauge](https://beamline.io/components/gauge): One value against a known range: a semicircle, a 270° dial or a full ring, filled or with a needle, coloured bands with their names (healthy, busy…
- [Radial chart](https://beamline.io/components/radial-chart): Progress of a few measures toward their targets as concentric rings, full or half circle, with a centre readout and a list of each ring's value, target…
- [Radar chart](https://beamline.io/components/radar-chart): A few series compared across the same five to eight dimensions as polygons on a polygon or circle grid; hover or arrow keys pick a dimension and read…
- [Scatter chart](https://beamline.io/components/scatter-chart): Two measures of many items against each other, one point per item, or a bubble chart when a third measure sizes the points: groups by colour and shape…
- [Area chart](https://beamline.io/components/area-chart): Amounts over time as filled areas: overlapping, stacked or as shares of 100%, five fills, two strokes, five curves, a range handle; gaps for missing…
- [Composed chart](https://beamline.io/components/composed-chart): Different measures on one time axis: bars, lines and areas per series, a left and a right value axis with their own formats, and reference lines.
- [Funnel chart](https://beamline.io/components/funnel-chart): People or deals moving through ordered steps, each step a bar narrowing from the first: the part lost between two steps stays beside the next as a fading…
- [Waffle chart](https://beamline.io/components/waffle-chart): Units of a whole as a grid of cells by category (seats used of a plan, tickets by channel): a 10×10 grid by default, hatched cells for units whose…
- [Slope chart](https://beamline.io/components/slope-chart): Change between two points in time per item, by value or by rank: labels on both sides that never collide, rising and falling told by the end marker (▲ ▼)…
- [Line chart](https://beamline.io/components/line-chart): Values over time as lines: curves, point markers, dashed series for forecasts, reference lines for limits and targets, an optional zero baseline and a…
- [Bar chart](https://beamline.io/components/bar-chart): Amounts by category as bars: columns or rows, grouped, stacked or as shares, reference lines, five looks (rounded, cells, trace, isometric, monospace), a…
- [Pie chart](https://beamline.io/components/pie-chart): A few shares of a whole as a pie or donut, with spaced slices, percent labels, a centre readout and a list of every slice with value and share; hovering…
- [Sparkline](https://beamline.io/components/sparkline): A compact trend beside its value: point along it or focus it and use ← → to read each point; nulls are gaps. TrendLine is the bare line.