Add Native Geographical Chart Support (Geo Maps) to Chart.js

[RickDeb2004]

Feature Proposal

---

[Feature Request]: Native Support for Geographical Charts (Geo Maps)

Type of Issue

• Bug
• Enhancement
• Question
• Documentation
• Other

Description

Chart.js is an excellent library for traditional chart types like bar, line, and pie charts, but it currently lacks native support for geographical charts (e.g., choropleth or bubble maps) to visualize area-based data on maps. This forces users to rely on third-party plugins like chartjs-chart-geo, which, while functional, introduces additional dependencies, setup complexity, and maintenance concerns (e.g., only 20 npm projects use it, per recent data). In contrast, libraries like React Nivo (@nivo/geo) offer built-in geo chart capabilities, making them more accessible for geospatial use cases.

Adding native geo chart support to Chart.js would enhance its versatility, aligning it with modern data visualization needs (e.g., regional sales, population density, or epidemiological data) without requiring external plugins. This feature would make Chart.js a more comprehensive solution for developers.

Proposed Feature

Implement a new chart type (e.g., type: 'geo') in Chart.js core, supporting:

• Choropleth Maps: Shade regions (e.g., countries, states) based on data values.
• Bubble Maps: Plot data points as sized circles on a map.
• Key Requirements:
  • Native handling of geo data formats (e.g., GeoJSON or TopoJSON).
  • Built-in projection support (e.g., Mercator, Albers) without external libraries like D3.
  • Configurable options for outlines, labels, and color scales.

Example Usage:

const chart = new Chart(ctx, {
  type: 'geo',
  data: {
    datasets: [{
      label: 'Population',
      data: [
        { id: 'USA', value: 331 },
        { id: 'CAN', value: 38 }
      ],
      geo: { features: worldCountries } // GeoJSON or TopoJSON
    }]
  },
  options: {
    geo: {
      projection: 'mercator',
      showOutline: true,
      colorScale: 'blues'
    }
  }
});

Why This Matters

• User Demand: Geospatial visualization is increasingly critical in fields like business analytics, public health, and climate science.
• Competitive Edge: Libraries like Nivo and Highcharts offer native geo support, putting Chart.js at a disadvantage for these use cases.
• Simplified Experience: Eliminating plugin reliance reduces setup time and ensures consistency with Chart.js’s lightweight ethos.

Current Workarounds

Users must integrate chartjs-chart-geo, which requires:

• Separate installation (npm i chartjs-chart-geo).
• Manual fetching of topojson files (e.g., us-atlas).
• Custom registration and configuration.

This adds friction and risks incompatibility with future Chart.js updates.

Suggested Implementation

• Core Additions:
  • New GeoController class extending Chart.Controller.
  • Built-in geo data parser (e.g., minimal TopoJSON support).
  • Projection utilities (e.g., inspired by d3-geo, but lightweight).
• Stretch Goals:
  • Preloaded basic map data (e.g., world countries) as an optional module.
  • Integration with existing plugins (e.g., datalabels) for annotations.

Steps to Reproduce (Current Limitation)

1. Try creating a choropleth map with vanilla Chart.js.
2. Observe no native geo type exists; plugin required.

Expected Behavior

A type: 'geo' option renders a map with data-driven regions or points.

Actual Behavior

No native support; throws an error or falls back to default behavior without a plugin.

Environment

• Chart.js version: 4.4.8 (latest)
• Browser: Any
• OS: Any

Additional Context

React Nivo’s @nivo/geo provides a great benchmark—its ResponsiveChoropleth component handles this use case natively. Chart.js could adopt a similar declarative approach while staying framework-agnostic.

---

Possible Implementation

Suggested Implementation

• Core Additions:
  • New GeoController class extending Chart.Controller.
  • Built-in geo data parser (e.g., minimal TopoJSON support).
  • Projection utilities (e.g., inspired by d3-geo, but lightweight).
• Stretch Goals:
  • Preloaded basic map data (e.g., world countries) as an optional module.
  • Integration with existing plugins (e.g., datalabels) for annotations.

[LeeLenaleee]

The vision of chart.js has always been to keep the core small, adding this will make it grow because a decent amount of new logic will be needed.

Also as you pointed out there already is a community chart type for this so in my opinion it's better to use that than to add it to the core which also increases the maintenance burden.

[adrianTNT]

I also would like to see this implemented in Chart.js What I like most about Chart.js is that you can add the code once and it works for years without having to worry that some external tools changed or are discontinued breaking my code. I seen this problem many times, Google charts did that too with a QR image/api.

A map like this one would be nice, I would donate something for such map(s) to be developed natively into ChartJS: https://www.pingdom.com/outages/

[RickDeb2004]

Should I start working on these ?
@adrianTNT @LeeLenaleee

[adrianTNT]

Should I start working on these ? @adrianTNT @LeeLenaleee

You mean start doing code then you can make a pull request to this repo? I am not fully familiar with GitHub functions, but for me it would help if this map feature will be accepted to be officially included / supported.

Maybe if code is not light enough to be included by default, it would be nice to be optionally included like this:

<script src="/chartjs/chart.js"></script>
<script src="/chartjs/chart-geo-maps.js"></script>

I am thinking these features would be nice:

• be able to highlight by graphically delimited / outlined country (like in above Pingdom map) Google charts also has this function
• then maybe to be able to add blips on screen, at certain coordinates, or by city name, I am sure we can find databases of city coordinates.
• tooltips/labels on the blips would be nice
• maybe not by default (too much work) but design it in a way for contributers to be able to add regions under countries. e.g delimitated states in US. For me, this regions detail is not a must, just an idea.

I could donate if something like this ends up being officially included / supported by the Chartjs repo but not sure what is best way to do this.

[LeeLenaleee]

The goal of chart.js was always to keep the core small.
And since there already is an external chart type that implements this I don't think we should add it in the core.

@etimberg what is your opinion about this?

[etimberg]

@LeeLenaleee I agree here. I don't think we can maintain this chart type. I would start by creating an external repo, similar to the ones listed in https://github.com/chartjs/awesome/?tab=readme-ov-file#charts

If the chart type grows, we can look at moving the repo inside the chartjs github org