API reference

All components are client components that also render on the server (pass topology explicitly for SSR). Data values are joined by official zero-padded codes: regions "01"-"16", provincias 3-digit, comunas 5-digit CUT.

Shared props (BaseMapProps<TFeature>)

Accepted by ChileMap, RegionComunasMap, and RegionProvinciasMap. TFeature is the level-specific feature type passed to callbacks.

Prop	Type	Default	Description
data	Record<string, number>	none	Values keyed by official code. Missing codes render with fillDefault; non-finite values are treated as missing. Every finite value participates in the scale domain.
colors	string[]	["#dbeafe", "#1e40af"]	Color ramp (2+ colors), sampled into one color per bin. A diverging scale is expressed by a three-stop ramp.
bins	number	5	Bin count for linear/quantile scales.
scaleType	"linear" | "quantile" | "threshold"	"linear"	Bin strategy. linear = equal-width, quantile = equal-count, threshold = explicit boundaries.
thresholds	number[]	none	Ascending inner boundaries; required when scaleType is "threshold", ignored otherwise.
colorFor	(feature: TFeature) => string | undefined	none	Per-feature override. Return undefined to fall back to the automatic scale.
featureLabel	(feature: TFeature) => string	feature.name	Presentation label for the default tooltip and each path's aria-label. Callback features keep the canonical BCN name.
fillDefault	string	"#e2e8f0"	Fill for units without a value.
stroke	string	"#ffffff"	Border color between units.
strokeWidth	number	0.5	Border width.
selected	string | null	null	Controlled selected code, highlighted per highlightMode and exposed as aria-pressed.
highlightStroke	string	"#0f172a"	Hover/selection border color.
highlightFill	string	"rgba(15, 23, 42, 0.18)"	Hover/selection overlay fill.
highlightMode	"stroke" | "fill" | "both"	"stroke"	Whether highlights use a border, a fill overlay, or both.
oceanicIslands	boolean	true	Render oceanic islands (west of longitude -76.5) in side insets. false draws mainland geometry only; fully oceanic units keep their data but render no shape.
onClick	(feature: TFeature) => void	none	Click/Enter/Space activation. Providing it makes features focusable buttons.
onHover	(feature: TFeature | null) => void	none	Hover and keyboard-focus callback; null when the pointer/focus leaves the map.
tooltip	((feature: TFeature) => ReactNode) | false	built-in	Custom tooltip render prop, or false to disable. The default shows the label and formatted value.
formatValue	(value: number) => string	toLocaleString	Formats the value in the default tooltip.
width, height	number	340, 800	viewBox size; the SVG scales responsively up to width.
className	string	none	Class on the wrapping <div>.
ariaLabel	string	per component	aria-label of the <svg>.

Keyboard interaction (when onClick is set)

An interactive SVG is exposed as a labeled group. Each unit is a role="button" path with a roving tab index (one Tab stop per map). Arrow keys move between units, Home/End jump to the first/last, Enter/Space activate, and focus shows the tooltip at the unit's centroid. aria-pressed reflects selected. Without onClick, the SVG is one labeled img and its internal paths are hidden from the accessibility tree.

<ChileMap> (ChileMapProps)

Prop	Type	Description
topology	Topology	Required. National regions TopoJSON. Import react-chile-map/data/regiones.json. Kept explicit so applications control when the national geometry loads.

Plus every shared prop with TFeature = RegionFeature.

<RegionComunasMap> / <RegionProvinciasMap>

Shared props plus (BaseRegionalMapProps<TFeature>):

Prop	Type	Default	Description
region	RegionCode	required	Region whose subdivisions render; drives the bundled lazy import.
topology	Topology	none	Override that bypasses the lazy loader (SSR, tests, preloading, custom cartography).
loadingFallback	ReactNode	built-in	Shown while the regional chunk loads.
errorFallback	ReactNode | (error) => ReactNode	built-in	Shown when loading or parsing fails.
onLoadError	(error: Error) => void	none	Loading/parsing error callback.
outlineStroke	string	"#64748b"	Outer region boundary color.
outlineStrokeWidth	number	strokeWidth * 2	Outer boundary width.

Successful topology imports are cached per region; stale in-flight results are ignored after region changes. Callback features: ComunaFeature adds region, province, provinceName; ProvinciaFeature adds region.

Optional regional data-key types

The public data prop remains Record<string, number> so dynamically loaded and custom topologies stay supported. Applications that use the bundled cartography can opt into exact key checking with the generated types:

import type { ComunaData, ProvinciaData } from "react-chile-map";

const comunaData = {
  "13101": 50,
  "13113": 82,
} satisfies ComunaData<"13">;

const provinciaData = {
  "131": 100,
  "132": 78,
} satisfies ProvinciaData<"13">;

<RegionComunasMap region="13" data={comunaData} />;
<RegionProvinciasMap region="13" data={provinciaData} />;

ComunaCode<R> and ProvinciaCode<R> expose the corresponding code unions directly. These four types cover the bundled codes for all 16 regions and are generated from the committed TopoJSON files.

SSR note: the bundled lazy loaders use dynamic JSON imports, which bundlers (Vite, webpack, Next) handle but raw Node ESM does not. On the server, pass topology explicitly.

React support: React 17, 18, and 19. With React 17, use a bundler or the CJS build; React 17 lacks the exports map raw Node ESM needs to resolve react/jsx-runtime.

Scales and <Legend>

createScale(options: CreateScaleOptions): MapScale
scaleFromData(data, options): MapScale   // domain = every finite value in data

MapScale exposes type, palette (one color per bin), thresholds (inner boundaries), fillDefault, and colorOf(value | undefined). The map components build their fills through scaleFromData with their own props, so a <Legend> created from the same inputs cannot diverge:

const scale = scaleFromData(data, { colors, bins: 6, type: "quantile" });
<ChileMap topology={regiones} data={data} colors={colors} bins={6} scaleType="quantile" />
<Legend scale={scale} formatValue={(v) => v.toLocaleString("es-CL")} showMissing />

<Legend> (LegendProps)

Prop	Type	Default	Description
scale	MapScale	required	Descriptor from createScale/scaleFromData.
formatValue	(value: number) => string	toLocaleString	Boundary label formatter.
title	ReactNode	none	Optional heading.
showMissing	boolean	false	Adds a swatch for missing values.
missingLabel	string	"No data"	Missing swatch label.
orientation	"column" | "row"	"column"	Layout direction.
className, ariaLabel	string	none	Styling and accessibility hooks.

Low-level helpers makePalette, quantize, and quantile remain exported.

Feature types

type RegionCode = "01" | … | "16";
interface MapFeature { code: string; name: string; value?: number }
type RegionFeature = MapFeature;
interface ProvinciaFeature extends MapFeature { region: RegionCode }
interface ComunaFeature extends MapFeature {
  region: RegionCode;
  province: string;      // first three CUT digits
  provinceName: string;
}

type Region13ComunaCode = ComunaCode<"13">;
type Region13ProvinciaCode = ProvinciaCode<"13">;
type Region13ComunaData = ComunaData<"13">;
type Region13ProvinciaData = ProvinciaData<"13">;

Development warnings

In development builds the package emits deduplicated, Strict Mode-safe console.warn diagnostics for: data codes absent from the topology, non-finite values, invalid colors/bins, scaleType: "threshold" without thresholds, duplicate feature codes, multiple topology objects, features with unexpected parent regions, and a controlled selected code missing from the topology. Production builds emit nothing. Ordinary missing values never warn.