Region Map
Regions shaded by a value: how it varies by state, province or country. Hover for the figures, click to zoom.
A choropleth made of plain SVG: no map library, no tiles. The shapes are data, so it is not tied to one place. Outlines for the United States, the United Kingdom, Spain, Germany, Canada and Australia ship with the library, each as its own import so an app only carries the one it uses. Pair it with RegionMapLegend, or use the finished card, the Region Map block.
Basic
Give it the shapes, a value for each region id and a scale. Four breaks make five bins, in the chart blue (the colours are the --color-map-bin-* tokens, so they follow light and dark mode).
- 20
- 40
- 60
- 80
Click to zoom
Click a region and the view eases to it with its neighbours still in frame. Click it again, or press Escape, to go back out. Reduced motion jumps instead of easing. Tab to the map, then use the arrow keys, Enter and Escape.
Selected: OR
Above and below zero
For growth, change or variance, set diverging: the bins that sit below zero turn orange, the rest stay blue, so the sign is never only a matter of how dark a blue is.
- -4.8%
- 0%
- +4.3%
- +8.9%
- +21%
Countries
Each country is its own module, so a UK app never downloads the US outlines. Every one is centred in the same 975 × 610 box.
Hover card
The default card shows the name and the value. Pass renderTooltip for anything richer: a rank, several metrics, a hint.
The Region Map block fills it with the rank, all three metrics and a “Select to zoom in” hint.
Linking it to a list or a legend
The map reports the region under the pointer and accepts one from outside, and the legend reports the band under the pointer. Wire the three together and pointing at any of them lights up the others: that is how the block works.
Try it in the Region Map block: hover a legend band, or a row of the list.
Your own regions
The shapes are an array of SVG paths, so counties, sales territories or a floor plan all work.
The country modules are generated by scripts/regions in the repository from Natural Earth and US Census boundaries, which are public domain.
Loading
Accessibility
- The map is a group with one tab stop. Arrow keys move between regions, Enter or Space selects, Escape clears the selection.
- Every region is a button with a label that carries its name and value, so the colour is never the only way to read it.
- Put the same figures in a list or table beside the map: it is the accessible version, and the block does this.
- Reduced motion turns the zoom easing and the loading shimmer off.
RegionMap props
| Prop | Type | Default | Description |
|---|---|---|---|
| regions | { id, name, d, box }[] | The shapes to draw. d is an SVG path, box is [x, y, width, height] of that path (used to zoom to it). Import a country's from @sakaniui/react/regions/… | |
| viewBox | [x, y, w, h] | The coordinate box the shapes live in. Each country module exports its own, e.g. UK_REGIONS_VIEWBOX. | |
| values | Record<string, number | null> | The value for each region, by id. Missing or null draws the neutral tone (and the legend can say "No data"). | |
| scale | { breaks: number[]; diverging?: boolean } | How values become colours. breaks are the edges between bins; diverging paints the bins below zero orange. Left out: no shading. | |
| selected / defaultSelected / onSelectedChange | string | null | The zoomed region, controlled or not. A click, Enter or Space selects; a second click or Escape clears. | |
| renderTooltip | (region, value) => ReactNode | The hover card. Default: the name and the value through formatValue. | |
| formatValue | (n) => string | String | Formats a value for the default card and the screen-reader label. |
| hovered | string | null | Outlines a region from outside (a list row, a legend) without a card. | |
| onHoverChange | (id | null) => void | The region under the pointer or keyboard focus. | |
| dimExcept | string[] | null | Fades every region whose id is not listed: the band a legend segment names. | |
| loading | boolean | Shimmers the map while data loads. | |
| aria-label | string | 'Map' | The accessible name of the map. |
RegionMapLegend props
| Prop | Type | Default | Description |
|---|---|---|---|
| scale | { breaks, diverging? } | The same scale the map uses. | |
| formatValue | (n) => string | String | Formats the break labels. |
| caption | ReactNode | An optional line under the key. | |
| activeBin | number | null | The lit bin: every other segment steps back. | |
| lockedBin | number | null | The bin that is held on (shown pressed). | |
| markBin | number | null | A bin to outline without dimming the others, e.g. the bin of the hovered region. | |
| onBinHover / onBinClick | (i) => void | Pointer or keyboard focus on a segment, and a click. Giving either makes the segments buttons. | |
| noData | boolean | Shows a "No data" swatch. |