Choropleth Map API

A world/region choropleth: your own GeoJSON, shaded by a threshold colour scale or an explicit category map - see the Choropleth Map demo.

Import

Web Component

import "@michi-vz/wc/choropleth-map-chart";
// <michi-vz-choropleth-map-chart> is now defined

Vanilla JS

import { mountChoroplethMapChart } from "@michi-vz/core";

const chart = mountChoroplethMapChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years": snapshots one period at a time over the distinct per-row `date` values, with a headless controller (`chart.timeline()`) plus an optional built-in play button + scrubber. Off by default; requires rows with `date`. Values tween between periods unless `interpolate: false`.
geography*	GeoJSON.FeatureCollection | GeoFeatureItem[]	-	The world/region geography to draw. A full GeoJSON FeatureCollection (its per-feature `id`/`properties.name` are read automatically) or a pre-normalized flat array. Core bundles NO topology data - import your own (e.g. a `world-atlas` TopoJSON converted via `topojson-client`, or a hand-curated GeoJSON) and pass it here.
dataSet*	ChoroplethDataItem[]	-	Choropleth values/colours, joined against `geography` (see `joinBy`).
title	string	-	Optional chart title rendered above the map
projection	GeoProjectionName	-	d3-geo / d3-geo-projection projection to use (default "geoRobinson", the legacy sdg-trade MapChoropleth default). `geoAlbersUsa` is a fixed composite projection - it ignores `rotate`/`center`/`parallels`.
projectionConfig	GeoProjectionConfig	-	Fine-tunes the chosen projection. Omitted fields fall back to the legacy MapChoropleth defaults (rotate [-18, 0], center [0, 10], base scale derived from width) rather than `projection.fitSize` - this matches the legacy chart's visual result exactly; pass your own values to frame a different geography extent (e.g. a single-region subset).
colorScale	{ domain: number[]; range: string[] }	-	Continuous choropleth encoding: a resolved hex `range` keyed to a numeric `domain`, built into a d3 `scaleThreshold`. Pass already-resolved colours (NOT a d3-scale-chromatic scheme name - core stays free of that dependency); generate the range yourself (e.g. via `d3-scale-chromatic` in your app) if you want a named scheme. Loses to `colorsMapping`.
noDataColor	string	DEFAULT_NO_DATA_COLOR	Fill for features with no matching `dataSet` row (default `#d2d7dd`).
joinBy	"id" | "name"	"id"	How `dataSet` rows join `geography` features: "id" (default) matches `ChoroplethDataItem.id` against `GeoFeatureItem.id` / GeoJSON `Feature.id` (stable codes such as ISO-A3), while "name" matches `label` against `GeoFeatureItem.name` / `properties.name` for data keyed by display name.
strokeColor	string	DEFAULT_STROKE_COLOR	Country border colour (legacy default: `#F4F7FC`, `colors.WHITE_SMOKE`)
strokeWidth	number	1	Country border width in px (default 1)
tooltipFormatter	(d: ChoroplethDataItem | { id: string; name?: string }) => string	-	Formats the tooltip for a hovered region. Matched rows receive the full `ChoroplethDataItem`; regions with no matching row receive the fallback `{ id, name }` shape (mirrors the legacy chart's "N/A" tooltip).
isLoading	boolean	-	Loading overlay (stale regions hidden while true)
isNodata	boolean | ((dataSet: ChoroplethDataItem[] | null | undefined) => boolean)	-	No-data predicate/flag; default = empty dataSet
noDataLabel	string	-	Text for the built-in no-data overlay
suppressDefaultOverlay	boolean	-	Set by a framework wrapper passing its own overlay node - suppresses the default overlay
onHighlightItem	(labels: string[]) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	900	Chart width in pixels
height	number	520	Chart height in pixels
margin	Margin	{ top: 40, right: 10, bottom: 10, left: 10 }	Inner margins (top/right/bottom/left, in px) reserved for axes, titles, and labels
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
colors	string[]	-	Categorical palette for series/labels without an explicit colour or colorsMapping entry
highlightItems	string[]	-	Labels to emphasise; all other marks dim
disabledItems	string[]	-	Labels to hide and exclude from scales/stacks
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas (faster for large datasets); getContext() is identical either way
locale	string	-	BCP-47 locale used for number and date formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so mark colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate updates with CSS transitions (default true)
onColorMappingGenerated	(mapping: Record<string, string>) => void	-	Called with the resolved label -> colour map after the chart assigns colours
onChartDataProcessed	(context: ChartContext) => void	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
onDataWarning	(warnings: DataWarning[]) => void	-	Called with any non-fatal data warnings (duplicate labels, non-finite values, non-monotonic dates, ...)

Events

The web component dispatches these bubbling CustomEvents (the engine exposes the same via the on* callbacks in the table above):

Event	Detail	Fires when
michi-vz:highlight	string[]	hover highlight changes
michi-vz:colormapping	Record<string, string>	a color mapping is generated
michi-vz:dataprocessed	ChartContext	data is (re)processed
michi-vz:datawarning	DataWarning[]	input warnings are detected (unmatched dataSet ids, features without ids, invalid geometry)

getContext()

mountChoroplethMapChart(el, props).getContext() returns a renderer-agnostic ChoroplethMapChartContext: stats.featureCount / matchedCount / unmatchedCount / valueDomain / min / max, a regions[] array (one row per feature: id, label, value?, color, matched), the resolved projection name, a deterministic natural-language summary, and an a11yTable listing every region + value + matched flag. See LLM context.

Source

Props are typed as ChoroplethMapChartProps in @michi-vz/core.