chartjs / chartjs/Chart.js

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

Open
#12,038 6 comments 2 reactions 0 assignees View on GitHub
status: implement externally type: enhancement
Dominant language
JavaScript
Stars
67.7k
Forks
11.9k
Avg merge
7h 39m
Merged PRs (30d)
5

Description

### Feature Proposal

---

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

## Type of Issue
- [ ] Bug
- [x] 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**:
```javascript
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.

![Image](https://github.com/user-attachments/assets/24af26f2-a7d5-4b50-90ee-ea3e67c3291f)

---

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

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.