2

Choropleth Chart

Previous

A world map with color-coded countries based on data values.

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// Sample GDP data for major countries (in trillion USD)
// IDs are ISO 3166-1 numeric codes used by world-atlas
const gdpData = [
  { id: "840", value: 25.5 }, // United States
  { id: "156", value: 17.9 }, // China
  { id: "392", value: 4.2 }, // Japan
  { id: "276", value: 4.1 }, // Germany
  { id: "356", value: 3.4 }, // India
  { id: "826", value: 3.1 }, // United Kingdom
  { id: "250", value: 2.8 }, // France
  { id: "380", value: 2.1 }, // Italy
  { id: "076", value: 1.9 }, // Brazil
  { id: "124", value: 2.1 }, // Canada
  { id: "643", value: 1.8 }, // Russia
  { id: "410", value: 1.7 }, // South Korea
  { id: "036", value: 1.7 }, // Australia
  { id: "724", value: 1.4 }, // Spain
  { id: "484", value: 1.3 }, // Mexico
  { id: "360", value: 1.2 }, // Indonesia
  { id: "528", value: 1.0 }, // Netherlands
  { id: "682", value: 1.1 }, // Saudi Arabia
  { id: "756", value: 0.8 }, // Switzerland
  { id: "792", value: 0.9 }, // Turkey
  { id: "616", value: 0.7 }, // Poland
  { id: "764", value: 0.5 }, // Thailand
  { id: "032", value: 0.6 }, // Argentina
  { id: "710", value: 0.4 }, // South Africa
  { id: "566", value: 0.5 }, // Nigeria
  { id: "818", value: 0.5 }, // Egypt
  { id: "586", value: 0.3 }, // Pakistan
  { id: "704", value: 0.4 }, // Vietnam
  { id: "152", value: 0.3 }, // Chile
  { id: "458", value: 0.4 }, // Malaysia
  { id: "702", value: 0.4 }, // Singapore
  { id: "608", value: 0.4 }, // Philippines
  { id: "578", value: 0.6 }, // Norway
  { id: "040", value: 0.5 }, // Austria
  { id: "372", value: 0.5 }, // Ireland
  { id: "784", value: 0.5 }, // UAE
  { id: "376", value: 0.5 }, // Israel
]

export function ChoroplethChartDemo() {
  return (
    <ChoroplethChart
      data={gdpData}
      legendTitle="GDP (Trillion $)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `$${v.toFixed(1)}T`}
      aspectRatio={2}
    />
  )
}

About

The Choropleth Chart displays a world map with countries colored according to their data values. It automatically fetches and renders all countries, requiring only the data values to be provided.

Features:

  • Built-in world map - No external GeoJSON required
  • Multiple projections - Natural Earth, Mercator, Equal Earth
  • Interactive tooltips - Hover to see country details
  • Color gradients - Customizable color scales
  • Responsive - Adapts to container width
  • Country-specific maps - Load regional maps for any country

Installation

pnpm dlx shadcn@latest add https://ui.simplifying.ai/r/choropleth-chart.json

Usage

import { ChoroplethChart } from "@/components/ui/charts"
 
// Data uses ISO 3166-1 numeric country codes
const data = [
  { id: "840", value: 25.5 }, // United States
  { id: "156", value: 17.9 }, // China
  { id: "392", value: 4.2 }, // Japan
  { id: "276", value: 4.1 }, // Germany
]
 
export function MyChart() {
  return (
    <ChoroplethChart
      data={data}
      legendTitle="GDP (Trillion $)"
      valueFormatter={(v) => `$${v.toFixed(1)}T`}
    />
  )
}

API Reference

PropTypeDefaultDescription
dataChoroplethDataPoint[]requiredValues by country ID
colorScalestring[]["#dbeafe", "#3b82f6", "#1e40af"]Color gradient (2-3 colors)
projection"naturalEarth" | "mercator" | "equalEarth" | "albersUsa""naturalEarth"Map projection type
showTooltipbooleantrueShow tooltip on hover
showLegendbooleantrueShow color legend
legendTitlestring"Value"Legend title text
aspectRationumber2Width to height ratio
valueFormatter(value: number) => stringtoLocaleStringFormat values
noDataColorstring"hsl(var(--muted))"Color for countries without data
geoUrlstringworld countriesCustom GeoJSON/TopoJSON URL
topojsonObjectstringauto-detectedObject name in TopoJSON
idPropertystring-Property name to use as feature ID
classNamestring-Additional CSS classes

Data Format

interface ChoroplethDataPoint {
  id: string // Region/country identifier
  value: number // The value to display
  label?: string // Optional label
}

Country Codes

The world map uses ISO 3166-1 numeric country codes. Common examples:

CountryCode
United States840
China156
Japan392
Germany276
United Kingdom826
France250
India356
Brazil076
Canada124
Australia036

Country Variants

The choropleth chart supports country-specific maps using the geoUrl prop. Below are examples for major countries showing their internal regions/states.

USA States

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// US States population data (in millions)
const populationData = [
  { id: "California", value: 39.5 },
  { id: "Texas", value: 29.1 },
  { id: "Florida", value: 21.5 },
  { id: "New York", value: 20.2 },
  { id: "Pennsylvania", value: 13.0 },
  { id: "Illinois", value: 12.8 },
  { id: "Ohio", value: 11.8 },
  { id: "Georgia", value: 10.7 },
  { id: "North Carolina", value: 10.4 },
  { id: "Michigan", value: 10.0 },
  { id: "New Jersey", value: 9.3 },
  { id: "Virginia", value: 8.6 },
  { id: "Washington", value: 7.6 },
  { id: "Arizona", value: 7.3 },
  { id: "Massachusetts", value: 7.0 },
  { id: "Tennessee", value: 6.9 },
  { id: "Indiana", value: 6.8 },
  { id: "Maryland", value: 6.2 },
  { id: "Missouri", value: 6.2 },
  { id: "Wisconsin", value: 5.9 },
  { id: "Colorado", value: 5.8 },
  { id: "Minnesota", value: 5.7 },
  { id: "South Carolina", value: 5.1 },
  { id: "Alabama", value: 5.0 },
  { id: "Louisiana", value: 4.7 },
  { id: "Kentucky", value: 4.5 },
  { id: "Oregon", value: 4.2 },
  { id: "Oklahoma", value: 4.0 },
  { id: "Connecticut", value: 3.6 },
  { id: "Utah", value: 3.3 },
  { id: "Iowa", value: 3.2 },
  { id: "Nevada", value: 3.1 },
  { id: "Arkansas", value: 3.0 },
  { id: "Mississippi", value: 3.0 },
  { id: "Kansas", value: 2.9 },
  { id: "New Mexico", value: 2.1 },
  { id: "Nebraska", value: 2.0 },
  { id: "Idaho", value: 1.9 },
  { id: "West Virginia", value: 1.8 },
  { id: "Hawaii", value: 1.5 },
  { id: "New Hampshire", value: 1.4 },
  { id: "Maine", value: 1.4 },
  { id: "Rhode Island", value: 1.1 },
  { id: "Montana", value: 1.1 },
  { id: "Delaware", value: 1.0 },
  { id: "South Dakota", value: 0.9 },
  { id: "North Dakota", value: 0.8 },
  { id: "Alaska", value: 0.7 },
  { id: "Vermont", value: 0.6 },
  { id: "Wyoming", value: 0.6 },
]

export function ChoroplethChartUSADemo() {
  return (
    <ChoroplethChart
      data={populationData}
      geoUrl="https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json"
      topojsonObject="states"
      legendTitle="Population (M)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `${v.toFixed(1)}M`}
      aspectRatio={1.6}
      projection="albersUsa"
    />
  )
}

China Provinces

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// China Provinces GDP data (in trillion CNY)
// Province names match the datamaps TopoJSON "name" property
const gdpData = [
  { id: "Guangdong", value: 12.4 },
  { id: "Jiangsu", value: 11.6 },
  { id: "Shandong", value: 8.3 },
  { id: "Zhejiang", value: 7.4 },
  { id: "Henan", value: 5.9 },
  { id: "Sichuan", value: 5.4 },
  { id: "Hubei", value: 5.0 },
  { id: "Fujian", value: 4.9 },
  { id: "Hunan", value: 4.6 },
  { id: "Shanghai", value: 4.3 },
  { id: "Anhui", value: 4.3 },
  { id: "Beijing", value: 4.0 },
  { id: "Hebei", value: 4.0 },
  { id: "Shaanxi", value: 3.0 },
  { id: "Jiangxi", value: 2.9 },
  { id: "Chongqing", value: 2.8 },
  { id: "Liaoning", value: 2.8 },
  { id: "Yunnan", value: 2.7 },
  { id: "Guangxi", value: 2.5 },
  { id: "Guizhou", value: 2.0 },
  { id: "Shanxi", value: 2.0 },
  { id: "Nei Mongol", value: 2.0 },
  { id: "Xinjiang", value: 1.6 },
  { id: "Tianjin", value: 1.6 },
  { id: "Heilongjiang", value: 1.5 },
  { id: "Jilin", value: 1.3 },
  { id: "Gansu", value: 1.1 },
  { id: "Hainan", value: 0.6 },
  { id: "Ningxia", value: 0.5 },
  { id: "Qinghai", value: 0.4 },
  { id: "Xizang", value: 0.2 },
]

export function ChoroplethChartChinaDemo() {
  return (
    <ChoroplethChart
      data={gdpData}
      geoUrl="https://raw.githubusercontent.com/markmarkoh/datamaps/master/src/js/data/chn.topo.json"
      topojsonObject="chn"
      idProperty="name"
      legendTitle="GDP (T CNY)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `¥${v.toFixed(1)}T`}
      aspectRatio={1.3}
      projection="mercator"
    />
  )
}

UK Local Authorities

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// UK Local Authorities population data (in millions)
// Names match the datamaps TopoJSON "name" property
const populationData = [
  { id: "Birmingham", value: 1.1 },
  { id: "Leeds", value: 0.8 },
  { id: "Glasgow", value: 0.6 },
  { id: "Sheffield", value: 0.6 },
  { id: "Bradford", value: 0.5 },
  { id: "Manchester", value: 0.5 },
  { id: "Liverpool", value: 0.5 },
  { id: "Edinburgh", value: 0.5 },
  { id: "Bristol", value: 0.5 },
  { id: "Cardiff", value: 0.4 },
  { id: "Belfast", value: 0.3 },
  { id: "Leicester", value: 0.4 },
  { id: "Wakefield", value: 0.3 },
  { id: "Coventry", value: 0.4 },
  { id: "Nottingham", value: 0.3 },
  { id: "Newcastle upon Tyne", value: 0.3 },
  { id: "Sunderland", value: 0.3 },
  { id: "Brighton and Hove", value: 0.3 },
  { id: "Hull", value: 0.3 },
  { id: "Plymouth", value: 0.3 },
]

export function ChoroplethChartUKDemo() {
  return (
    <ChoroplethChart
      data={populationData}
      geoUrl="https://raw.githubusercontent.com/markmarkoh/datamaps/master/src/js/data/gbr.topo.json"
      topojsonObject="gbr"
      idProperty="name"
      legendTitle="Population (M)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `${v.toFixed(1)}M`}
      aspectRatio={1.5}
      projection="mercator"
    />
  )
}

Germany States

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// Germany Bundesländer population data (in millions)
// State names match the GeoJSON "name" property (German names)
const populationData = [
  { id: "Nordrhein-Westfalen", value: 17.9 },
  { id: "Bayern", value: 13.1 },
  { id: "Baden-Württemberg", value: 11.1 },
  { id: "Niedersachsen", value: 8.0 },
  { id: "Hessen", value: 6.3 },
  { id: "Sachsen", value: 4.1 },
  { id: "Rheinland-Pfalz", value: 4.1 },
  { id: "Berlin", value: 3.6 },
  { id: "Schleswig-Holstein", value: 2.9 },
  { id: "Brandenburg", value: 2.5 },
  { id: "Sachsen-Anhalt", value: 2.2 },
  { id: "Thüringen", value: 2.1 },
  { id: "Hamburg", value: 1.9 },
  { id: "Mecklenburg-Vorpommern", value: 1.6 },
  { id: "Saarland", value: 1.0 },
  { id: "Bremen", value: 0.7 },
]

export function ChoroplethChartGermanyDemo() {
  return (
    <ChoroplethChart
      data={populationData}
      geoUrl="https://raw.githubusercontent.com/isellsoap/deutschlandGeoJSON/master/2_bundeslaender/4_niedrig.geo.json"
      idProperty="name"
      legendTitle="Population (M)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `${v.toFixed(1)}M`}
      aspectRatio={1.3}
      projection="mercator"
    />
  )
}

France Regions

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// France Régions population data (in millions)
// Region names match the GeoJSON "nom" property
const populationData = [
  { id: "Île-de-France", value: 12.3 },
  { id: "Auvergne-Rhône-Alpes", value: 8.0 },
  { id: "Hauts-de-France", value: 6.0 },
  { id: "Nouvelle-Aquitaine", value: 6.0 },
  { id: "Occitanie", value: 5.9 },
  { id: "Grand Est", value: 5.6 },
  { id: "Provence-Alpes-Côte d'Azur", value: 5.1 },
  { id: "Pays de la Loire", value: 3.8 },
  { id: "Normandie", value: 3.3 },
  { id: "Bretagne", value: 3.3 },
  { id: "Bourgogne-Franche-Comté", value: 2.8 },
  { id: "Centre-Val de Loire", value: 2.6 },
  { id: "Corse", value: 0.3 },
]

export function ChoroplethChartFranceDemo() {
  return (
    <ChoroplethChart
      data={populationData}
      geoUrl="https://raw.githubusercontent.com/gregoiredavid/france-geojson/master/regions-version-simplifiee.geojson"
      idProperty="nom"
      legendTitle="Population (M)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `${v.toFixed(1)}M`}
      aspectRatio={1.2}
      projection="mercator"
    />
  )
}

Brazil States

Loading map...
"use client"

import { ChoroplethChart } from "@/components/ui/charts"

// Brazil Estados population data (in millions)
// State names match the GeoJSON "name" property
const populationData = [
  { id: "São Paulo", value: 46.6 },
  { id: "Minas Gerais", value: 21.4 },
  { id: "Rio de Janeiro", value: 17.5 },
  { id: "Bahia", value: 14.9 },
  { id: "Paraná", value: 11.6 },
  { id: "Rio Grande do Sul", value: 11.4 },
  { id: "Pernambuco", value: 9.6 },
  { id: "Ceará", value: 9.2 },
  { id: "Pará", value: 8.7 },
  { id: "Santa Catarina", value: 7.3 },
  { id: "Maranhão", value: 7.1 },
  { id: "Goiás", value: 7.1 },
  { id: "Amazonas", value: 4.2 },
  { id: "Paraíba", value: 4.1 },
  { id: "Espírito Santo", value: 4.1 },
  { id: "Rio Grande do Norte", value: 3.5 },
  { id: "Alagoas", value: 3.4 },
  { id: "Mato Grosso", value: 3.5 },
  { id: "Piauí", value: 3.3 },
  { id: "Distrito Federal", value: 3.1 },
  { id: "Mato Grosso do Sul", value: 2.8 },
  { id: "Sergipe", value: 2.3 },
  { id: "Rondônia", value: 1.8 },
  { id: "Tocantins", value: 1.6 },
  { id: "Acre", value: 0.9 },
  { id: "Amapá", value: 0.9 },
  { id: "Roraima", value: 0.6 },
]

export function ChoroplethChartBrazilDemo() {
  return (
    <ChoroplethChart
      data={populationData}
      geoUrl="https://raw.githubusercontent.com/codeforamerica/click_that_hood/master/public/data/brazil-states.geojson"
      idProperty="name"
      legendTitle="Population (M)"
      colorScale={["#bfdbfe", "#60a5fa", "#1e40af"]}
      valueFormatter={(v) => `${v.toFixed(1)}M`}
      aspectRatio={1.1}
      projection="mercator"
    />
  )
}

Adding Custom Country Maps

You can display any country's regional map by providing a GeoJSON or TopoJSON URL. Here's how to find and use map data for your country:

Step 1: Find GeoJSON/TopoJSON Data

Recommended sources (CORS-enabled):

  1. Datamaps - Comprehensive world subdivisions (200+ countries)

    https://raw.githubusercontent.com/markmarkoh/datamaps/master/src/js/data/{iso3}.topo.json
    

    Replace {iso3} with ISO 3166-1 alpha-3 code (e.g., ind for India, chn for China)

  2. US Atlas (npm package) - USA states and counties

    https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json
    
  3. World Atlas (npm package) - World countries

    https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json
    

Step 2: Inspect the Data Structure

Use browser DevTools or a JSON viewer to find:

  • Object name (for TopoJSON): Look for objects.{name} (e.g., objects.states, objects.ind)
  • ID property: Check features[0].properties for the name field (e.g., name, NAME, nom)

Step 3: Create Your Data

Match your data IDs to the map's region names:

// Example: Japan Prefectures
const data = [
  { id: "Tokyo", value: 14.0 },
  { id: "Osaka", value: 8.8 },
  { id: "Kanagawa", value: 9.2 },
  // ... more prefectures
]

Step 4: Configure the Chart

<ChoroplethChart
  data={data}
  geoUrl="https://raw.githubusercontent.com/markmarkoh/datamaps/master/src/js/data/jpn.topo.json"
  topojsonObject="JPN" // Check your TopoJSON's object name
  idProperty="name" // Property containing region names
  legendTitle="Population (M)"
  valueFormatter={(v) => `${v.toFixed(1)}M`}
/>

ISO 3166-1 Alpha-3 Country Codes

Common country codes for Datamaps URLs:

CountryCodeURL
Indiaind.../ind.topo.json
Chinachn.../chn.topo.json
Japanjpn.../jpn.topo.json
Russiarus.../rus.topo.json
Germanydeu.../deu.topo.json
Francefra.../fra.topo.json
Brazilbra.../bra.topo.json
Australiaaus.../aus.topo.json
Canadacan.../can.topo.json
Mexicomex.../mex.topo.json
South Koreakor.../kor.topo.json
Spainesp.../esp.topo.json
Italyita.../ita.topo.json

Full list: ISO 3166-1 alpha-3 codes

Customization

Custom Colors

<ChoroplethChart
  data={data}
  colorScale={["#fef3c7", "#f59e0b", "#b45309"]} // Yellow-orange
/>

Different Projection

<ChoroplethChart
  data={data}
  projection="mercator" // or "equalEarth", "albersUsa" (for USA maps)
/>

Note: Use albersUsa for USA maps - it repositions Alaska and Hawaii for better visualization.

Custom Value Formatting

<ChoroplethChart
  data={data}
  valueFormatter={(v) => `${v.toFixed(0)}%`}
  legendTitle="Percentage"
/>

Adjust Aspect Ratio

Different countries have different shapes. Adjust aspectRatio accordingly:

// Wide countries (Russia, USA)
<ChoroplethChart data={data} aspectRatio={2.2} />
 
// Tall countries (Chile, Japan)
<ChoroplethChart data={data} aspectRatio={0.5} />
 
// Square-ish countries (France, Germany)
<ChoroplethChart data={data} aspectRatio={1.2} />

Notes

  • Choropleth maps are ideal for visualizing geographic data distributions and regional comparisons
  • The component comes with a built-in world map, no external GeoJSON files needed for world visualizations
  • Use ISO 3166-1 numeric country codes for world maps to ensure proper country matching
  • Custom regional maps (states, provinces, districts) can be loaded via the geoUrl prop
  • The albersUsa projection is specifically optimized for USA maps with Alaska and Hawaii repositioned
  • Color scales should use 2-3 colors for optimal visual distinction
  • Tooltip interactions are enabled by default for better data exploration
  • Consider your data range when choosing color scales - sequential data works best with gradient scales