ChoroplethMap

A US choropleth map using D3's Albers USA projection, which repositions Alaska and Hawaii to the bottom left. Supports state-level, county-level, and HSA-level (Health Service Areas) rendering via the geoType prop.

You must provide your own TopoJSON topology data via the topology prop. We recommend the us-atlas package:

npm install us-atlas

State-level maps: use us-atlas/states-10m.json
County or HSA maps: use us-atlas/counties-10m.json (includes both county and state boundaries)

vue

<script setup>
import { ChoroplethMap } from "@cfasim-ui/charts";
import statesTopo from "us-atlas/states-10m.json";
import countiesTopo from "us-atlas/counties-10m.json";
</script>

<!-- State map -->
<ChoroplethMap :topology="statesTopo" :data="stateData" />

<!-- County map -->
<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  :data="countyData"
/>

Examples

Basic with state data

Cases by State

Cases

51.367.583.8

vue

<script setup>
import statesTopo from "us-atlas/states-10m.json";
</script>

<ChoroplethMap
  :topology="statesTopo"
  :data="[
    { id: '06', value: 100 },
    { id: '36', value: 80 },
    { id: '48', value: 90 },
    { id: '12', value: 70 },
    { id: '17', value: 60 },
  ]"
  title="Cases by State"
  :legend-title="'Cases'"
  :height="400"
/>

Custom color scale

Severity

51.367.583.8

vue

<ChoroplethMap
  :topology="statesTopo"
  :data="[
    { id: 'California', value: 100 },
    { id: 'Texas', value: 85 },
    { id: 'Florida', value: 70 },
    { id: 'New York', value: 90 },
  ]"
  :color-scale="{ min: '#fff5f0', max: '#a50f15' }"
  :legend-title="'Severity'"
  :height="400"
/>

Theming (`theme`)

All map paint styling lives in one theme prop: the base fill for features without data, the feature stroke (+ strokeWidth), the state-borders mesh over county/HSA maps (+ bordersWidth), an exterior outline (+ outlineWidth), a background wash, and the hover/focus highlight. Every color accepts any CSS color the page can express, including var(), light-dark(), and color-mix(), resolved against the map container's cascade. When the effective values change (a site light/dark toggle, an OS scheme flip, a custom-property redefinition), the map repaints on its own — in both the SVG and canvas renderers. colorScale colors resolve the same way, so theme tokens work there too.

The outline is the exterior boundary of the rendered geography — the national outline, or the selected state's boundary in single-state mode — drawn on top of interior borders with its own color and width. It's off by default and turns on when a visible color resolves.

Themed map with an exterior outline

Cases

557085

vue

<ChoroplethMap
  :topology="statesTopo"
  :data="stateData"
  :theme="{
    fill: 'light-dark(#e2e8f0, #334155)',
    stroke: 'light-dark(#f8fafc, #0f172a)',
    outline: 'light-dark(#334155, #cbd5e1)',
    outlineWidth: 1.5,
  }"
  title="Themed map with an exterior outline"
  :legend-title="'Cases'"
  :height="400"
/>

Every channel's default routes through a --choropleth-* custom property, so a stylesheet alone can theme every map on a page — JS theme values always win:

css

:root {
  color-scheme: light dark; /* required for light-dark() to engage */
  --choropleth-fill: light-dark(#dbe4d7, #24332a);
  --choropleth-stroke: light-dark(#f4f7f2, #131e17);
  --choropleth-outline: light-dark(#3f5245, #93ac9b); /* enables the outline */
  --choropleth-background: light-dark(
    #f4f7f2,
    #131e17
  ); /* enables a background */
  --choropleth-highlight: light-dark(#000, #fff);
  --choropleth-borders: transparent; /* falls back to the stroke color */
}

Theme key	Default	Notes
`fill`	`var(--choropleth-fill, light-dark(#ddd, #3f3f46))`	Fill for features without a data value
`stroke`	`var(--choropleth-stroke, light-dark(#fff, #18181b))`	Interior feature borders
`strokeWidth`	`0.5` (halved on county/HSA maps)	Explicit values apply as-is on every geoType; `0` disables
`borders`	`var(--choropleth-borders, transparent)`	State mesh over county/HSA maps; falls back to `stroke`; hide with `bordersWidth: 0`
`bordersWidth`	`1`	`0` disables
`outline`	`var(--choropleth-outline, transparent)`	Exterior boundary; off until a visible color resolves
`outlineWidth`	`1`	`0` disables
`background`	`var(--choropleth-background, transparent)`	Wash behind the map; off until a visible color resolves
`highlight`	`var(--choropleth-highlight, light-dark(#000, #fff))`	Hover/focus stroke; per-item `FocusItem.stroke` wins
`markerColor`	`--choropleth-city-marker` / `-label-color` vars	`cities` overlay dot + label color
`markerHalo`	`--choropleth-city-halo` var	Halo around marker dots and labels
`markerHaloWidth`	`0.9`	Dot halo width in CSS px; `0` disables
`markerOpacity`	`1`	Opacity of the whole marker layer

Breaking change

theme replaces the former noDataColor, strokeColor, and strokeWidth props: use theme.fill, theme.stroke, and theme.strokeWidth instead.

Threshold color scale

Use an array of ThresholdStop objects instead of a linear scale. Each stop defines a min threshold — values at or above that threshold get the stop's color. The highest matching stop wins.

Risk Level

Risk Low Some Moderate High

vue

<ChoroplethMap
  :topology="statesTopo"
  :data="stateData"
  :color-scale="[
    { min: 0, color: '#fee5d9', label: 'Low' },
    { min: 10, color: '#fcae91', label: 'Some' },
    { min: 30, color: '#fb6a4a', label: 'Moderate' },
    { min: 60, color: '#cb181d', label: 'High' },
  ]"
  title="Risk Level"
  :legend-title="'Risk'"
  :height="400"
/>

Categorical color scale

Use an array of CategoricalStop objects to map string values to colors. Each stop defines a value to match and a color to apply.

Risk Category

Risk low medium high

vue

<ChoroplethMap
  :topology="statesTopo"
  :data="stateData"
  :color-scale="[
    { value: 'low', color: '#fee5d9' },
    { value: 'medium', color: '#fb6a4a' },
    { value: 'high', color: '#cb181d' },
  ]"
  title="Risk Category"
  :legend-title="'Risk'"
  :height="400"
/>

Pan and zoom

Maps are fully static by default — tooltips, hover, click-select, and programmatic focus zoom all work, but there are no zoom gestures and no controls. That's the right mode when clicks mean navigation instead of exploration (see the state-map pattern below); a parent driving focus provides its own way back (e.g. a "Back" button that clears the focus).

Add the zoom prop to enable the interaction. The map is then static until the first zoom — clicks and taps only ever select; it's the first zoom gesture that switches panning on. The scroll wheel never zooms inline, so the map can't hijack page scrolling. A grey hint overlaid on the top of the map ("Double click to zoom" / "Double tap to zoom") advertises the gesture until it's been used; pass :zoom-hint="false" to hide it.

Desktop: double-click zooms in place (shift+double-click zooms out), or press + in the always-present + / − / reset control stack in the top-left corner. The first zoom — including a programmatic focus zoom — starts the pan/zoom mode; from then on, drag pans the map. The reset button (a counterclockwise arrow) animates back to the full extent (clearing any focus); − and reset are disabled while the map is at its full extent.
Touch: a double tap expands the map to fill the window, zoomed in on the tapped point; single taps select features inline. Inside the expanded view, one finger pans, a pinch zooms, and a tap selects — its tooltip slides up as a bottom sheet; the +/−/reset controls sit top-left and a close (✕) button top-right returns to the inline map at full extent. A single finger over the inline map still scrolls the page.

Filling the window is always an activated state: whether entered via the menu's Fullscreen item or a double tap, pan/zoom works immediately and the controls are present — no double-click needed first. The scroll wheel (and trackpad pinch) zooms there too, since page scrolling is locked while the map fills the window.

Prefer in-place zooming on touch? Set :touch-expand="false" — a double tap (or a pinch) zooms the inline map on that point instead of expanding it. From there one finger pans, a pinch zooms, and taps keep selecting; the +/−/reset controls render inline, and reset restores the original static, page-scrollable state. Fullscreen is unaffected: that view stays continuously interactive and its reset only recenters.

Full-page mode (`zoom-mode="scroll"`)

When the map is the page — a dedicated map route, a dashboard panel, a kiosk — the activation step just gets in the way, and there's no page scroll to protect. Pair zoom with zoom-mode="scroll" to make the map immediately interactive: the wheel (and trackpad pinch) zooms, dragging pans, and touch gestures work inline with no tap-to-expand step. The +/−/reset controls are always shown and the hint is suppressed.

vue

<ChoroplethMap
  :topology="statesTopo"
  :data="stateData"
  zoom
  zoom-mode="scroll"
/>

County-level map

Set geoType="counties" to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Double-click (or double-tap on touch) to explore — useful for dense county data.

This demo also wires up an interactive tooltip (tooltip-trigger="hover"): hover a county on desktop, or tap one on touch, and it works the same before and after zooming in.

Cases by County

Cases

62.57587.5

Double click to zoom

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  zoom
  tooltip-trigger="hover"
  :data="[
    { id: '06037', value: 100 },
    { id: '36061', value: 90 },
    { id: '17031', value: 85 },
    { id: '48201', value: 65 },
    { id: '04013', value: 60 },
  ]"
  title="Cases by County"
  :legend-title="'Cases'"
  :height="400"
/>

Tighter national fit (`tight-fit`)

The Albers USA projection places Alaska and Hawaii in the bottom-left corner, and by default the whole composite is fit into view — so Alaska's western tail pushes the contiguous US in from the edges. Set tight-fit to crop that overhang and let the lower-48 fill more of the frame: Alaska's tail (and Hawaii) clip into the lower-left corner. Pass a number in 0–1 (e.g. :tight-fit="0.5") to crop only partway.

Works on national state, county, and HSA maps — it's a no-op only in single-state mode. (County features are split by FIPS prefix; HSAs, whose ids are HSA codes rather than FIPS, are identified through the built-in FIPS-to-HSA table.)

Cases by State (tight fit)

Cases

708090

vue

<!-- Crop Alaska's overhang so the lower-48 fills the frame -->
<ChoroplethMap :topology="statesTopo" tight-fit :data="data" />

<!-- ...or crop only partway -->
<ChoroplethMap :topology="statesTopo" :tight-fit="0.5" :data="data" />

City markers (`cities`)

Pass a cities array to overlay decorative point markers with name labels. Each entry is { name, coordinates: [lng, lat], capital?, minZoom? }. Every city is a dot; capital cities are labeled first and never dropped, while any other label that can't be placed without overlapping is dropped (its dot stays), so labels never collide. The overlay is non-interactive — the choropleth's own hover/click is unaffected — and the markers pan/zoom with the map while staying a constant on-screen size. It works with both the SVG and canvas (renderer) backends.

Level-of-detail: on a zoomable map (zoom), each city has a minZoom and shows only once the map is zoomed to scaleK >= minZoom, so you can reveal the biggest cities first and progressively add more as the user zooms in. nationalCityMarkers() / stateCityMarkers() assign these tiers by population automatically (the capital always shows). A city without its own minZoom falls back to the cities-min-zoom prop (default 2) — set that to 1 for a flat "always visible" layer, or pass { tiered: false } to the selectors. The overview below shows the biggest cities; double-click to zoom in and reveal more:

100 most-populous US cities and the capital

Double click to zoom

vue

<script setup>
import { ChoroplethMap } from "@cfasim-ui/charts";
import { nationalCityMarkers } from "@cfasim-ui/charts/us-cities";
import statesTopo from "us-atlas/states-10m.json";

// Washington, DC (flagged as the capital) + the 100 most-populous US cities.
const cities = nationalCityMarkers();
</script>

<!-- zoom in one level to reveal the cities -->
<ChoroplethMap :topology="statesTopo" :cities="cities" zoom />

In a single-state map, pass that state's cities so its capital and top cities show:

Double click to zoom

vue

<!-- Sacramento (capital) + California's most-populous cities -->
<ChoroplethMap
  :topology="countiesTopo"
  state="California"
  geo-type="counties"
  :cities="stateCityMarkers('06')"
  zoom
/>

Bundled US city data (`@cfasim-ui/charts/us-cities`)

nationalCityMarkers() and stateCityMarkers() come from the @cfasim-ui/charts/us-cities subpath — a ~5 KB gzipped dataset (Natural Earth, public domain) of the 100 most-populous US cities plus every state capital and DC. It's a separate entry point, so consumers who don't use it never pull it into their bundle.

import {
  usCities,
  nationalCityMarkers,
  stateCityMarkers,
} from "@cfasim-ui/charts/us-cities";

nationalCityMarkers(); //=> DC (capital) + top 100 cities, tiered by population
nationalCityMarkers({ limit: 25 }); //=> DC + top 25
nationalCityMarkers({ tiered: false }); //=> flat layer, no per-city minZoom
stateCityMarkers("48"); //=> Austin (capital) + top Texas cities
usCities; //=> the raw UsCity[] to build your own selection

Only the national capital is flagged on the national map; a state's own capital is flagged in its single-state view. A flagged capital's label is placed first and never dropped for collisions; it carries a .choropleth-city-label-capital class if you want to style it, but by default it looks like every other label — the marker is a plain dot too.

Styling: the default marker style is dark dots and labels with a thin white halo, which reads over any map fill in either color scheme. The theme prop's marker keys configure the layer — markerColor (dots + labels), markerHalo (the halo around both), markerHaloWidth (dot halo width in CSS px), and markerOpacity (the whole layer). Any CSS color works. A stylesheet can alternatively set the CSS custom properties on .choropleth-cities (--choropleth-city-marker, --choropleth-city-label-color, --choropleth-city-halo); theme keys win when both are set.

HSA-level map

Set geoType="hsas" to render Health Service Area boundaries. HSAs are dissolved from county boundaries using a built-in FIPS-to-HSA mapping. Use 6-digit HSA codes as IDs. State borders are overlaid for context.

This demo pairs tooltip-trigger="hover" with a custom #tooltip slot — hover an HSA on desktop, or tap one on touch, before or after zooming in.

Cases by HSA

Cases

51.367.583.8

Double click to zoom

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="hsas"
  zoom
  tooltip-trigger="hover"
  :data="[
    { id: '010259', value: 100 },
    { id: '060766', value: 90 },
    { id: '120159', value: 85 },
    { id: '090121', value: 70 },
    { id: '110061', value: 60 },
  ]"
  title="Cases by HSA"
  :legend-title="'Cases'"
  :height="400"
>
  <template #tooltip="{ id, name, value }">
    <div style="font-weight: 600">{{ name }}</div>
    <div style="opacity: 0.7; font-size: 0.85em">HSA {{ id }}</div>
    <div v-if="value != null">Cases: {{ value }}</div>
    <div v-else style="opacity: 0.6">No data</div>
  </template>
</ChoroplethMap>

Single-state map (`state`)

Set the state prop to render just one state's outline with its counties or hsas inside it — no surrounding states — and the projection zooms to fit it. Accepts a state name ("California") or a 2-digit FIPS code ("06"). This needs a counties topology (the same us-atlas/counties-10m.json). data can stay national; only features inside the selected state are drawn and colored.

This demo also opts for the quieter touch flow: :touch-expand="false" makes a double tap (or pinch) zoom in place instead of expanding to fill the window, and :zoom-hint="false" drops the grey gesture hint.

California cases by county

Cases

557085

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  state="California"
  zoom
  :touch-expand="false"
  :zoom-hint="false"
  :data="[
    { id: '06037', value: 100 }, // Los Angeles
    { id: '06073', value: 80 }, // San Diego
    { id: '06059', value: 65 }, // Orange
  ]"
  title="California cases by county"
  :legend-title="'Cases'"
  :height="400"
/>

Switch geo-type="hsas" to fill the same state with Health Service Areas instead. An unrecognized state value logs a warning and falls back to the full national map.

Click to focus (`v-model:focus`)

Bind the focus prop to pan and zoom to a specific feature. Pass a feature id (FIPS code, HSA code, or name) — or an array of ids to focus on a region. With v-model:focus, clicking an unfocused feature focuses it and clicking the focused feature toggles back off. If a tooltip is configured, focusing shows that feature's tooltip. Users can keep exploring around the focused area; the built-in reset button clears focus and snaps back to the full extent.

Each focus target's outline can be styled by passing a FocusItem object: style picks the dash pattern ("solid" | "dashed" | "dotted"), stroke the color, and strokeWidth the width in CSS px. In-place highlights default to pure black/white following the theme (light-dark(#000, #fff)); cross-geoType overlays default to white.

Set :focus-zoom="false" to highlight (and draw cross-geoType overlays) without panning or zooming — useful for a click-to-select interaction where the map should stay put while a side panel shows the details.

Selection works the same on touch: a single-finger tap on a feature emits stateClick and toggles focus, inline or inside the expanded view. (Inline with zoom on, the selection fires after the brief double-tap window.) A tap also stands in for hover — it applies the hover highlight, emits stateHover, and shows the feature's tooltip (anchored to the feature inline; sliding up as a bottom sheet in the expanded view); only continuous hover tracking is off on touch, for performance.

Click-to-focus interactions usually pair best with :touch-expand="false", as in the demos below — a double tap zooms in place while taps keep selecting, so the map stays in your layout instead of taking over the window.

Counties are tiny without a zoom — focus is a natural fit for drill-down.

Click a county to focus

Cases

62.57587.5

Double click to zoom

vue

<script setup>
import { ref } from "vue";
const focused = ref(null);
</script>

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  v-model:focus="focused"
  :focus-zoom-level="8"
  zoom
  :touch-expand="false"
  :data="data"
  title="Click a county to focus"
>
  <template #tooltip="{ name, value }">
    <div style="font-weight: 600">{{ name }}</div>
    <div v-if="value != null">Cases: {{ value }}</div>
    <div v-else style="opacity: 0.6">No data</div>
  </template>
</ChoroplethMap>

Color by HSA, interact by county (`dataGeoType`)

Set dataGeoType when your data is keyed by a coarser geography than the one you want to render. Each county fills with its parent HSA's value (via the built-in FIPS → HSA mapping); hover, click, and focus still operate on the county geometry, and you can layer an HSA outline on top with a FocusItem.

HSA-keyed data on a county map

Cases

38.852.566.3

Double click to zoom

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  data-geo-type="hsas"
  zoom
  renderer="canvas"
  :touch-expand="false"
  :data="hsaData"
  :focus="[{ id: '06043' }, { id: '060737', geoType: 'hsas', style: 'dashed' }]"
  title="HSA-keyed data on a county map"
/>

Mixing levels on one map (`data[].geoType`)

dataGeoType re-keys all the data at once. When only some regions report at a different level — most of the country has county estimates, but California only published a statewide number — give those rows their own geoType instead. The state is then drawn at that level: one merged California shape carrying the state value, with every other state still split into counties.

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  :data="[
    { id: '36061', value: 12 }, // county rows as usual
    { id: '06', value: 85, geoType: 'states' }, // …and California as a whole
  ]"
/>

The substituted region is a normal feature: it fills from its own row, hovers and clicks as one unit, reports its own name (California) in the tooltip, and can be focused by its id.

County estimates, with California and Texas reported statewide

Rate

24.849.574.3

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  renderer="canvas"
  :data="[
    ...countyRows,
    { id: '06', value: 85, geoType: 'states' },
    { id: '48', value: 15, geoType: 'states' },
  ]"
/>

It works in the other direction too — a state-level map where one state is broken out into counties. The whole state is re-tiled, so its counties without a row of their own render as no-data:

State estimates, with New York broken out by county

Rate

24.348.572.8

vue

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="states"
  :data="[
    { id: '06', value: 70 },
    { id: '48', value: 30 },
    ...newYorkCountyRows.map((r) => ({ ...r, geoType: 'counties' })),
  ]"
/>

Rules to keep in mind:

A whole state is the unit. One off-level row re-tiles its entire state, so a single county row on a state map splits all of that state's counties out.
Any pair of levels works (states / counties / hsas), in either direction, as long as the topology can supply them — splitting a state into counties or HSAs needs counties-10m.json, not states-10m.json. HSA substitution waits for the lazily-loaded FIPS→HSA table and leaves the base map untouched until it arrives.
Off-level rows ignore dataGeoType. They're looked up by their own id, so a map can use dataGeoType for its base features and still mix.
One level per state. If two rows claim the same state at different levels, the first wins and a warning is logged. A row whose id resolves to no state is ignored (also with a warning) and the base map renders as usual.
Ids can be codes or feature names ("06" or "California"), resolved in the row's own geoType.

Outline a focused feature's parent

Use v-model:focus together with a computed that derives a parent feature (e.g. an HSA from a county via fipsToHsa). Pass both as a FocusItem array — the focused county lights up as usual and the parent HSA renders on top as a dashed overlay (stroke: "#666" here — default is white).

fipsToHsa and hsaNames ship from the @cfasim-ui/charts/hsa-mapping subpath so consumers that don't need HSA lookups don't pay for the ~25 KB of mapping data.

Click a county to outline its HSA

Cases

38.852.566.3

Double click to zoom

vue

<script setup>
import { ref, computed } from "vue";
import { fipsToHsa } from "@cfasim-ui/charts/hsa-mapping";

const focusedCounty = ref(null);
const focus = computed(() => {
  const fips = focusedCounty.value;
  if (!fips) return null;
  const hsa = fipsToHsa[fips];
  return hsa
    ? [fips, { id: hsa, geoType: "hsas", style: "dashed", stroke: "#666" }]
    : fips;
});
</script>

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  data-geo-type="hsas"
  zoom
  :touch-expand="false"
  :data="hsaData"
  :focus="focus"
  @update:focus="focusedCounty = typeof $event === 'string' ? $event : null"
  title="Click a county to outline its HSA"
/>

Pass tooltip-value-format to format numeric values shown in the tooltip (both the native SVG <title> and the interactive HTML tooltip). Use the #tooltip slot if you want full control over the tooltip's content.

US population (2020)

25M29.9M34.7M

vue

<ChoroplethMap
  :topology="statesTopo"
  :data="[
    { id: '06', value: 39538223 },
    { id: '48', value: 29145505 },
    { id: '12', value: 21538187 },
    { id: '36', value: 20201249 },
  ]"
  :tooltip-value-format="(v) => v.toLocaleString('en-US')"
  title="US population (2020)"
  :height="300"
/>

Canvas rendering (`renderer="canvas"`)

For dense maps — every US county, HSAs, or anything that feels sluggish on mobile — set renderer="canvas". Instead of one DOM path per feature, the whole map paints into a single <canvas>: zooming, panning, and hover/tap highlights redraw in a few milliseconds regardless of feature count, and DOM memory stays flat. Interactions are identical (hover, click/tap selection, focus, every zoom mode and touch flow); hit-testing runs through an offscreen picking bitmap, so it stays pixel-accurate.

Differences from the default SVG renderer:

The menu offers Fullscreen and Save as PNG only (there is no SVG DOM to serialize; the PNG exports straight off the rendering canvas).
There is no per-feature <title> fallback or per-feature DOM for assistive tech — configure an interactive tooltip (tooltip-trigger or the #tooltip slot), or stay on SVG where that fallback matters.
renderer is fixed at mount.

The dense county demo below uses it.

Dense county map

Renders every US county with a value and a custom tooltip slot, on the canvas backend.

All US counties — tooltip perf demo

24.849.574.3

Double click to zoom

vue

<script setup>
import countiesTopo from "us-atlas/counties-10m.json";

// One row per county
const data = countiesTopo.objects.counties.geometries.map((g, i) => ({
  id: String(g.id).padStart(5, "0"),
  value: (i * 37) % 100,
}));
</script>

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  :data="data"
  zoom
  renderer="canvas"
>
  <template #tooltip="{ id, name, value }">
    <div style="font-weight: 600">{{ name }}</div>
    <div style="opacity: 0.7; font-size: 0.85em">FIPS {{ id }}</div>
    <div>Value: {{ value }}</div>
  </template>
</ChoroplethMap>

Custom tooltip content (`#tooltip` slot)

Use the #tooltip slot to render any Vue template — components, scoped styles, multi-line layouts — instead of the default name: value. The slot receives { id, name, value, feature } for the hovered region. Providing the slot automatically enables interactive (HTML) tooltips, so you don't need to set tooltip-trigger.

US population (2020)

19.5M26.2M32.9M

vue

<ChoroplethMap :topology="statesTopo" :data="data" title="US population (2020)">
  <template #tooltip="{ name, value }">
    <div style="font-weight: 600">{{ name }}</div>
    <div v-if="typeof value === 'number'">
      Pop: {{ value.toLocaleString("en-US") }}
    </div>
    <div v-else style="opacity: 0.6">No data</div>
  </template>
</ChoroplethMap>

Accessibility

The map's individual regions aren't exposed to assistive tech, so the map announces itself with a single accessible name. When it has a title, the root element gets role="figure" and an aria-label set to the title, so screen readers announce it as a labeled figure while the menu and reset controls stay reachable.

Set ariaLabel to give screen readers a fuller summary than the visible title (it overrides title for the accessible name only):

vue

<ChoroplethMap
  :topology="usStates"
  :data="cases"
  title="Cases by state"
  aria-label="US map shaded by case count per state, highest in the Southeast"
/>

Pass role to override the default, e.g. role="img" to expose the map as a single image (note this hides the inner menu/reset controls from assistive tech).

Props

Prop	Type	Required	Default
`topology`	`Topology`	Yes	—
`data`	`StateData[]`	No	—
`geoType`	`GeoType`	No	`"states"`
`dataGeoType`	`GeoType`	No	—
`state`	`string`	No	—
`width`	`number`	No	—
`height`	`number`	No	—
`tightFit`	`boolean \| number`	No	`false`
`colorScale`	`ChoroplethColorScale \| ThresholdStop[] \| CategoricalStop[]`	No	—
`title`	`string`	No	—
`titleStyle`	`TitleStyle`	No	—
`role`	`string`	No	—
`ariaLabel`	`string`	No	—
`legendStyle`	`LabelStyle`	No	—
`theme`	`MapTheme`	No	—
`menu`	`boolean \| string`	No	`true`
`legend`	`boolean`	No	`true`
`legendTitle`	`string`	No	—
`zoom`	`boolean`	No	`false`
`zoomMode`	`"activate" \| "scroll"`	No	`"activate"`
`touchExpand`	`boolean`	No	`true`
`zoomHint`	`boolean`	No	`true`
`tooltipTrigger`	`"hover" \| "click"`	No	—
`tooltipFormat`	`(data: {

  id: string` | No | — |

| name | string | Yes | — | | value | number \| string | No | — | | tooltipValueFormat | NumberFormat | No | — | | tooltipClamp | "none" \| "chart" \| "window" | No | "window" | | focus | FocusValue | No | — | | focusZoomLevel | number | No | 4 | | focusZoom | boolean | No | true | | renderer | "svg" \| "canvas" | No | "svg" | | fullscreenTarget | string \| HTMLElement | No | — | | cities | CityMarker[] | No | — | | citiesMinZoom | number | No | 2 |

StateData

interface StateData {
  /** FIPS code (e.g. "06" for California, "06037" for LA County) or name */
  id: string;
  value: number | string;
  /**
   * Level of *this row*, when it differs from the map's `geoType`. The row's
   * state is re-tiled at this level — see "Mixing levels on one map".
   */
  geoType?: GeoType;
}

ChoroplethColorScale

Any CSS color works, including var() and light-dark() — scale colors resolve against the map's container and re-resolve on page theme changes.

interface ChoroplethColorScale {
  /** Minimum color (any CSS color). Default: "#e5f0fa" */
  min?: string;
  /** Maximum color (any CSS color). Default: "#08519c" */
  max?: string;
}

ThresholdStop

Pass an array of ThresholdStop as colorScale for discrete color buckets instead of a linear gradient. The highest matching min wins.

interface ThresholdStop {
  /** Lower bound (inclusive). Values at or above this get this color. */
  min: number;
  color: string;
  /** Optional label for the legend (defaults to the min value) */
  label?: string;
}

CategoricalStop

Pass an array of CategoricalStop as colorScale to map string values to colors. States whose value matches a stop's value get that color; unmatched values get the theme's base fill.

interface CategoricalStop {
  /** The categorical value to match */
  value: string;
  /** CSS color string */
  color: string;
}

MapTheme

All keys are optional; unset keys fall back to their --choropleth-* custom property (see Theming).

interface MapTheme {
  /** Base fill for features without a data value (any CSS color). */
  fill?: string;
  /** Interior feature borders (any CSS color). */
  stroke?: string;
  /** Feature border width in CSS px, constant at any zoom. 0 disables. */
  strokeWidth?: number;
  /** State-boundary mesh over county/HSA maps. Falls back to `stroke`. */
  borders?: string;
  /** State-borders mesh width in CSS px. Default 1; 0 disables. */
  bordersWidth?: number;
  /** Exterior boundary, drawn on top of interior borders. Off by default. */
  outline?: string;
  /** Exterior outline width in CSS px. Default 1; 0 disables. */
  outlineWidth?: number;
  /** Background wash behind the map features. Off by default. */
  background?: string;
  /** Hover/focus highlight stroke. */
  highlight?: string;
  /** Marker overlay (`cities` prop): dot + label color. */
  markerColor?: string;
  /** Marker overlay: halo color around dots and labels. */
  markerHalo?: string;
  /** Dot halo width in CSS px. Default 0.9; 0 disables. */
  markerHaloWidth?: number;
  /** Opacity of the whole marker layer. Default 1. */
  markerOpacity?: number;
}

FocusItem

The focus prop accepts a bare id, a FocusItem, or an array of either. Use objects when you want to pin features from a different geoType than the base map, or pick a non-default outline style.

interface FocusItem {
  /** Feature id (FIPS code, HSA code) or name. */
  id: string;
  /** Defaults to the map's geoType. Cross-geoType items render as
   * non-interactive outlines on top of the base map. */
  geoType?: "states" | "counties" | "hsas";
  /** Outline style. "solid" (default) matches the hover highlight;
   * "dashed" uses long dashes; "dotted" uses small round dots. */
  style?: "solid" | "dashed" | "dotted";
  /** Stroke color for cross-geoType overlay paths. Default: "#fff". */
  stroke?: string;
}

ChoroplethMap ​

Examples ​

Basic with state data ​

Custom color scale ​

Theming (theme) ​

Threshold color scale ​

Categorical color scale ​

Pan and zoom ​

Full-page mode (zoom-mode="scroll") ​

County-level map ​

Tighter national fit (tight-fit) ​

City markers (cities) ​

Bundled US city data (@cfasim-ui/charts/us-cities) ​

HSA-level map ​

Single-state map (state) ​

Click to focus (v-model:focus) ​

Color by HSA, interact by county (dataGeoType) ​

Mixing levels on one map (data[].geoType) ​

Outline a focused feature's parent ​

Custom tooltip number format ​

Canvas rendering (renderer="canvas") ​

Dense county map ​

Custom tooltip content (#tooltip slot) ​

Accessibility ​

Props ​

StateData ​

ChoroplethColorScale ​

ThresholdStop ​

CategoricalStop ​

MapTheme ​

FocusItem ​

ChoroplethMap

Examples

Basic with state data

Custom color scale

Theming (`theme`)

Threshold color scale

Categorical color scale

Pan and zoom

Full-page mode (`zoom-mode="scroll"`)

County-level map

Tighter national fit (`tight-fit`)

City markers (`cities`)

Bundled US city data (`@cfasim-ui/charts/us-cities`)

HSA-level map

Single-state map (`state`)

Click to focus (`v-model:focus`)

Color by HSA, interact by county (`dataGeoType`)

Mixing levels on one map (`data[].geoType`)

Outline a focused feature's parent

Custom tooltip number format

Canvas rendering (`renderer="canvas"`)

Dense county map

Custom tooltip content (`#tooltip` slot)

Accessibility

Props

StateData

ChoroplethColorScale

ThresholdStop

CategoricalStop

MapTheme

FocusItem