Choropleth

Overview

The Choropleth component wraps Nivo's ResponsiveChoroplethwith MetricUI's card shell, theming, format engine, cross-filtering, and drill-down. It accepts two data formats: native ChoroplethDatum[] ({ id, value }) or flat DataRow[] with configurable field names.

Basic Example

Import worldFeatures from MetricUI and pass it alongside your region data. Feature IDs are standard ISO 3166-1 alpha-3 codes (e.g. "USA", "GBR", "HND").

import { Choropleth, worldFeatures } from "metricui";

const populationData = [
  { id: "USA", value: 340_000_000 },
  { id: "GBR", value: 67_000_000 },
  { id: "DEU", value: 83_000_000 },
  { id: "IND", value: 1_417_000_000 },
  { id: "CHN", value: 1_408_000_000 },
  { id: "BRA", value: 213_000_000 },
  // ...
];

<Choropleth
  data={populationData}
  features={worldFeatures}
  title="Population"
  tooltipLabel="Population"
  format="compact"
  scaleType="sqrt"
  projectionType="naturalEarth1"
  projectionScale={120}
  height={450}
/>

Projections

The projectionType prop controls the map projection. Available options: mercator (default), naturalEarth1, equalEarth, orthographic.

<Choropleth
  data={areaData}
  features={worldFeatures}
  title="Land Area (km²)"
  tooltipLabel="Area"
  format={{ style: "number", suffix: " km²", compact: true }}
  projectionType="equalEarth"
  projectionScale={130}
  colors={["#fef3c7", "#f59e0b", "#b45309", "#78350f"]}
  height={400}
/>

Custom Colors

Pass a colors array to define the sequential color scale. Colors are interpolated between stops based on the data domain.

<Choropleth
  data={populationData}
  features={worldFeatures}
  title="Population — Cool Palette"
  format="compact"
  scaleType="sqrt"
  projectionType="naturalEarth1"
  projectionScale={120}
  colors={["#ecfdf5", "#6ee7b7", "#059669", "#064e3b"]}
  height={400}
/>

Data Format

Choropleth accepts two data formats. The native format uses { id, value } objects. For flat DataRow arrays, specify idField and valueField to map columns.

// Native format — id is an ISO 3166-1 alpha-3 code
const data = [
  { id: "USA", value: 340_000_000 },
  { id: "GBR", value: 67_000_000 },
];

// Flat DataRow format
const rows = [
  { country_code: "USA", population: 340_000_000 },
  { country_code: "GBR", population: 67_000_000 },
];

<Choropleth
  data={rows}
  features={worldFeatures}
  idField="country_code"
  valueField="population"
/>

Bundled Features

MetricUI bundles worldFeatures — world country boundaries at 110m resolution (~105KB). Feature IDs are standard ISO 3166-1 alpha-3 codes (USA, GBR, DEU, etc.).

import { Choropleth, worldFeatures } from "metricui";

// worldFeatures is ready to use — no extra packages needed
<Choropleth data={myData} features={worldFeatures} />

For other maps (US states, EU countries, custom regions), provide your own GeoJSON. Recommended sources:

• world-atlas — World and US TopoJSON (npm)
• natural-earth-vector — High-res country/state/province shapefiles
• us-atlas — US states and counties TopoJSON (npm)

Props

Data Shape

// Nivo-native format
interface ChoroplethDatum {
  id: string;    // ISO 3166-1 alpha-3 code (e.g. "USA", "GBR")
  value: number;
}

// Flat-row format (converted via idField + valueField)
const rows = [
  { country: "USA", population: 331000000 },
  { country: "GBR", population: 67000000 },
];
// idField="country" valueField="population"

Notes

• Uses forwardRef.
• The features prop is **required** — you must provide GeoJSON geometry. Use worldFeatures for world maps or usStatesFeatures for US state maps.
• worldFeatures and usStatesFeatures are helper exports that load TopoJSON and convert to GeoJSON features. Import them from metricui/geo.
• scaleType controls how values map to colors. Use 'log' for data with extreme ranges (e.g. population) and 'sqrt' for moderate skew. 'linear' works for uniform distributions.
• tooltipLabel customizes what the value is called in the tooltip (e.g. 'Population' instead of 'value'). Defaults to the valueField name.
• Feature ids must match data ids. For world maps, use ISO 3166-1 alpha-3 codes (USA, GBR, DEU). For US states, use FIPS codes or state abbreviations depending on your GeoJSON.
• The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.

Related Components