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)

<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

<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

<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"
/>

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.

<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.

<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"
/>

County-level map with pan and zoom

Set geoType="counties" to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Use pan and zoom props to enable interactive navigation — useful for dense county data.

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="counties"
  pan
  zoom
  :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"
/>

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.

<ChoroplethMap
  :topology="countiesTopo"
  geo-type="hsas"
  pan
  zoom
  :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"
/>

Props

Prop	Type	Required	Default
topology	Topology	Yes	—
data	StateData[]	No	—
geoType	GeoType	No	"states"
width	number	No	—
height	number	No	—
colorScale	ChoroplethColorScale | ThresholdStop[] | CategoricalStop[]	No	—
title	string	No	—
noDataColor	string	No	"#ddd"
strokeColor	string	No	"#fff"
strokeWidth	number	No	0.5
menu	boolean | string	No	true
legend	boolean	No	true
legendTitle	string	No	—
zoom	boolean	No	false
pan	boolean	No	false
tooltipTrigger	"hover" | "click"	No	—
tooltipFormat	`(data: {

  id: string` | No | — |

| name | string | Yes | — | | value | number \| string | No | — |

StateData

interface StateData {
  /** FIPS code (e.g. "06" for California, "06037" for LA County) or name */
  id: string;
  value: number | string;
}

ChoroplethColorScale

interface ChoroplethColorScale {
  /** Minimum color (CSS color string). Default: "#e5f0fa" */
  min?: string;
  /** Maximum color (CSS color string). 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 noDataColor.

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