ChoroplethMap
Charts

ChoroplethMap

Displays region values as tile colors using a discrete sequential scale.

Component behavior

ChoroplethMap displays region values as colored, equal-size tiles. Tile positions come from a grid layout rather than geographic boundaries.

Use cases
  • One numeric value for each named region.
  • Spatial patterns across geographic or operational regions.
  • Region sets small enough to retain readable labels.
Alternatives

BarChart: category ranking or precise magnitude comparison is required.

Heatmap: the two axes represent variables rather than locations.

DataGrid: the view requires exact values, sorting, or multiple measures per region.

DonutChart: a few regions are compared by share of one total.

Props

layout supplies each region's code, name, and 1-based row and column. data supplies values matched by code. A missing entry or value: null renders a hatched no-data tile.

ChoroplethMapProps props
PropTypeDefaultDescription
dataMapRegion[]—Region code, value, and optional label. Null indicates no data. Layout determines placement.
layoutMapLayoutCell[]US_STATE_GRIDThe tiles to draw, by code, at 1-based row/column. Grid size is derived from the largest row and column present.
colorstring"var(--m-color-primary)"Base hue for the color scale. Steps blend the surface and base color from 18% to 100%.
stepsnumber5Number of discrete ramp steps. Past about seven, adjacent steps stop being distinguishable.
domain[number, number]—Value range for the color scale. Defaults to zero through the maximum value.
formatValue(value: number) => string—Formats the legend's end labels, the native tile title, and the aria-label. Defaults to Math.round.
legendLabelReactNode—Label describing the legend values.
showLegendbooleantrueShow the ramp legend. It always includes the hatched no-data swatch.
showCodesbooleantruePrint the region code inside each tile. On the ramp's top two steps the code flips to the on-primary ink.
tileSizenumber26Tile edge in pixels; the grid gap is a fixed 2px. Below ~16 the codes are no longer legible.
onSelect(region: MapRegion, cell: MapLayoutCell) => void—Enables tile selection. Called only for layout cells with a matching data entry.
renderTooltip(region: MapRegion | null, cell: MapLayoutCell) => ReactNode—Tooltip anchored below the hovered tile. The region is null when the layout cell has no data entry.

Examples

US state grid

US_STATE_GRID is the default layout. Supply data for a US tile map. Tiles include a native title and an aria-label containing the name and formatted value. Use renderTooltip for additional content.

ChoroplethMap

Controlling the ramp

steps controls color resolution and domain controls the mapped value range. Values outside the domain clamp to the endpoint colors. The examples compare the default zero-to-maximum domain with a clipped domain for skewed data.

ChoroplethMap ramp

A custom layout

Custom layouts contain region codes and grid coordinates. They can represent cloud regions, warehouses, or other named locations. Grid dimensions derive from the largest row and column; gaps are allowed.

ChoroplethMap custom layout

Selectable tiles

Tiles are disabled buttons when onSelect is omitted. When onSelect is provided, selecting a tile calls the handler with its region data and layout cell.

ChoroplethMap onSelect
ImportTSX
import { ChoroplethMap, US_STATE_GRID } from "@solarius/onset";
import type { MapLayoutCell, MapRegion } from "@solarius/onset";

<ChoroplethMap
  data={[
    { code: "CA", value: 850 },
    { code: "TX", value: 620 },
    { code: "AK", value: null },
  ]}
  layout={US_STATE_GRID}
  color="var(--m-color-warn)"
  steps={6}
  domain={[0, 900]}
  legendLabel="Active users"
  tileSize={28}
  onSelect={(region, cell) => console.log(cell.name, region.value)}
/>;