ztd chartsHome

Map · Intermediate

Choropleth map

Regions on a real map, shaded by their value in steps.

Open in playground
Use when
Where is it high and where is it low: a rate or average per country, state or province, where the geographic pattern is the message
Avoid when
The values are totals that grow with area or population (large regions look heavier), or every region must be equally visible (use tileMap)

Try it

38

Choropleth map

Checkout conversion (%)
Canada converts bestIntermediate

Hover over the chart, or Tab in and use the arrow keys to move between items. The numbers are sample data.

Variants

Named looks for this chart. Each one is the example above with a few options or fields changed. The CLI (ztd-charts example choropleth --variant <id>) and the MCP server know the same names.

Europe

Sample data

US states

Sample data

South Korea

Sample data

Your own GeoJSON

Sample data

Code

Choropleth.tsx
import { ChartCard, Choropleth } from "ztd-charts";

const data = [
  {"country":"United States","rate":3.8},
  {"country":"Canada","rate":4.8},
  {"country":"Mexico","rate":2.1},
  {"country":"Brazil","rate":1.9},
  {"country":"Argentina","rate":1.6},
  {"country":"Chile","rate":2.3},
  // … 31 more rows
];

export function Example() {
  return (
    <ChartCard number="38" title="Choropleth map" subtitle="Checkout conversion (%)" takeaway="Canada converts best" level="intermediate" replay>
      <Choropleth
        data={data}
        region="country"
        value="rate"
        map="world"
        unit="%"
      />
    </ChartCard>
  );
}

Props

<Choropleth> takes these props. Rows marked Common work the same on every chart.

35 props

Prop
dataRequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]
regionRequiredRegion name or code, matched to a region of options.mapstring | (d, i) => string
valueRequiredValue fieldstring | (d, i) => number
mapMap. "auto" picks the registered map that matches the most region values. "world" is 177 countries (Natural Earth 1:110m, de facto borders; ISO 3166-1 alpha-2, alpha-3 and numeric codes, English and common names), "us-states" is the 50 US states and DC with Alaska and Hawaii moved below (postal codes, FIPS codes, names), "kr-sido" is South Korea's 16 first-level regions from 2026-07-01. Or a GeoJSON FeatureCollection of Polygon and MultiPolygon features in longitude and latitude degrees. ztd-charts/server, the CLI and the MCP server load every built-in map; in the browser import the map from ztd-charts/geo/<name> and pass it to registerMapanyDefault "auto"
focusShow only part of the world map, cropped and enlarged. Countries of other regions inside the frame are drawn pale and take no data. Regions follow UN M49"europe" | "asia" | "africa" | "americas" | "oceania"
featureIdGeoJSON property that holds the region id. Without it: feature.id, then the id or code propertystring
featureNameGeoJSON property that holds the region name. Without it: the name or NAME propertystring
legendShow the color legend. It also shows a No data swatch when some regions have no valuebooleanDefault true
legendLabelsNames at both ends of the legendstring[]
colorReverseDarkest color for the smallest value, for rankings where 1st should stand out. The default highlight moves to the smallest value toobooleanDefault false
colorCenterValue that gets the lightest color. Values above take the accent color and values below take gray, so gains and losses split there (for example 0)number
colorStepsNumber of color steps. The legend shows each step, and hovering a step leaves only its regionsnumberDefault 5
rankingRanked list of the highest and lowest regions beside the map. "auto" shows it when the chart is at least 600px wideanyDefault "auto"
labelsLanguage of region names on the Korean map. "auto" uses Korean names when a matched region value contains Hangul, otherwise the locale's language"auto" | "ko" | "en"Default "auto"
heightCommonHeight in px. Without it, each chart picks a default that fits its widthnumber
widthCommonFixed width in px. Without it, the chart fits its parentnumber
highlightCommonItem to highlight. An index, a name, an array, or "max" | "min" | "first" | "last" | "none"number | string | (number|string)[] | "max" …
formatCommonValue format. "number" | "integer" | "percent" (values are already percents: 42 → "42%") | "ratio" (0.42 → "42%") | "compact" | "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) | "decimal" or Intl.NumberFormat options"number" | "percent" | "compact" | …
unitCommonUnit appended to values. For example "%" or "ms"string
localeCommonLocale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider localestringDefault "en-US"
animateCommonEntry and update animationbooleanDefault true
durationCommonAnimation length (ms)number
easingCommonMotion curve"spring" | "easeOut" | "easeInOut" | "linear"Default "spring"
staggerCommonDelay between items as they enter (ms)number
reducedMotionCommon"auto" follows the OS setting. true always turns motion offanyDefault "auto"
animateOnViewCommonPlay when the chart scrolls into viewbooleanDefault true
showLabelsCommonLabels drawn on the chart (values and names)booleanDefault true
tooltipCommonShow tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left outtooltipDefault true
syncIdCommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside itstring
ariaLabelCommonName for screen readersstring
descriptionCommonDescription for screen readers. Built from the data when omittedstring
onHoverCommonRuns when hover or keyboard focus moves to another item(e: ChartEvent | null) => void
onClickCommonRuns on click, Enter or Space(e: ChartEvent) => void
replayKeyCommonReplays the entry animation when it changesstring | number
themeCommonChanges theme tokens for this chart onlyPartial<ChartTheme>

Also in Map