chartjs-chart-geo

A Choropleth chart (type: choropleth) renders maps where areas are filled based on numerical values.

Data Structure

Each data point in the datasets[].data array must contain:

• .feature: The TopoJSON feature object to render.
• .value: The numerical value used for coloring.

To process TopoJSON files, use the ChartGeo.topojson utility (exposed in the global context) to convert raw TopoJSON data into features.

Configuration Example

const us = await fetch('https://cdn.jsdelivr.net/npm/us-atlas/states-10m.json').then((r) => r.json());

// Extract features using ChartGeo.topojson
const nation = ChartGeo.topojson.feature(us, us.objects.nation).features[0];
const states = ChartGeo.topojson.feature(us, us.objects.states).features;

const alaska = states.find((d) => d.properties.name === 'Alaska');
const california = states.find((d) => d.properties.name === 'California');

const config = {
  type: 'choropleth',
  data: {
    labels: ['Alaska', 'California'],
    datasets: [{
      label: 'States',
      outline: nation, // Optional: outline to compute bounds
      showOutline: true,
      data: [
        { value: 0.4, feature: alaska },
        { value: 0.3, feature: california }
      ]
    }]
  },
  options: {
    scales: {
      projection: {
        projection: 'albersUsa' // Use D3 projection names without the 'geo' prefix
      }
    }
  }
};

const us = await fetch('https://cdn.jsdelivr.net/npm/us-atlas/states-10m.json').then((r) => r.json());

// whole US for the outline
const nation = ChartGeo.topojson.feature(us, us.objects.nation).features[0];
// individual states
const states = ChartGeo.topojson.feature(us, us.objects.states).features;

const alaska = states.find((d) => d.properties.name === 'Alaska');
const california = states.find((d) => d.properties.name === 'California');

const config = {
  data: {
    labels: ['Alaska', 'California'],
    datasets: [{
      label: 'States',
      outline: nation, // ... outline to compute bounds
      showOutline: true,
      data: [
        {
          value: 0.4,
          feature: alaska // ... the feature to render
        },
        {
          value: 0.3,
          feature: california
        }
      ]
    }]
  },
  options: {
    scales: {
      projection: {
        projection: 'albersUsa' // ... projection method
      }
    }
  }
};

Because the ESM build supports tree shaking and has no side effects, Chart.js will not automatically register the new controllers or scales. You must manually register them.

Option A: Manual Registration

Use Chart.register to include the necessary components:

import { Chart } from 'chart.js';
import { ChoroplethController, GeoFeature, ColorScale, ProjectionScale } from 'chartjs-chart-geo';

Chart.register(ChoroplethController, GeoFeature, ColorScale, ProjectionScale);

const chart = new Chart(ctx, {
  type: 'choropleth',
  data: { /* ... */ }
});

Option B: Using Wrapper Classes

Import the specialized chart class directly:

import { ChoroplethChart } from 'chartjs-chart-geo';

const chart = new ChoroplethChart(ctx, {
  data: { /* ... */ }
});

import { Chart } from 'chart.js';
import { ChoroplethController, GeoFeature, ColorScale, ProjectionScale } from 'chartjs-chart-geo';

// register controller in chart.js and ensure the defaults are set
Chart.register(ChoroplethController, GeoFeature, ColorScale, ProjectionScale);

const chart = new Chart(document.getElementById('canvas').getContext('2d'), {
  type: 'choropleth',
  data: {
    // ...
  },
});

To create a Bubble Map where bubbles represent areas (often used to visualize data proportional to geographic size), you need to provide a data object containing geographic features and bubble coordinates, along with a config object that specifies the chart type as a bubble map.

In this mode, the chart typically uses the bubbleMap chart type. The data structure requires a datasets array where each dataset contains data points. Each point in the data array should correspond to a geographic feature or coordinate and include a value that determines the bubble's size.

// Note: This example relies on external config and data files
// defined in the repository structure.

import { config } from './area';

// The configuration includes the chart type and options
// The data includes the geographic features and bubble values
new Chart(ctx, {
  type: 'bubbleMap',
  data: config.data,
  options: config.options
});