{"id":13595141,"url":"https://github.com/sgratzl/chartjs-chart-geo","last_synced_at":"2025-05-14T19:09:41.590Z","repository":{"id":40551358,"uuid":"210985315","full_name":"sgratzl/chartjs-chart-geo","owner":"sgratzl","description":"Chart.js Choropleth and Bubble Maps","archived":false,"fork":false,"pushed_at":"2025-04-12T15:09:11.000Z","size":17323,"stargazers_count":369,"open_issues_count":13,"forks_count":46,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-14T19:09:35.992Z","etag":null,"topics":["bubble-chart","chartjs","chartjs-plugin","choropleth","d3-geo","javascript","map"],"latest_commit_sha":null,"homepage":"https://www.sgratzl.com/chartjs-chart-geo/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgratzl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["sgratzl"]}},"created_at":"2019-09-26T02:48:19.000Z","updated_at":"2025-04-30T13:30:21.000Z","dependencies_parsed_at":"2024-03-14T03:23:33.348Z","dependency_job_id":"22cd4b5a-1157-4769-8c18-df880a4d7790","html_url":"https://github.com/sgratzl/chartjs-chart-geo","commit_stats":{"total_commits":358,"total_committers":7,"mean_commits":"51.142857142857146","dds":0.06703910614525144,"last_synced_commit":"60030f4f145ae252d5b2fd1ab0b5575ab796d6e8"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgratzl%2Fchartjs-chart-geo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgratzl%2Fchartjs-chart-geo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgratzl%2Fchartjs-chart-geo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgratzl%2Fchartjs-chart-geo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgratzl","download_url":"https://codeload.github.com/sgratzl/chartjs-chart-geo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubble-chart","chartjs","chartjs-plugin","choropleth","d3-geo","javascript","map"],"created_at":"2024-08-01T16:01:44.701Z","updated_at":"2025-05-14T19:09:40.233Z","avatar_url":"https://github.com/sgratzl.png","language":"TypeScript","funding_links":["https://github.com/sponsors/sgratzl"],"categories":["TypeScript","Charts"],"sub_categories":[],"readme":"# Chart.js Geo\n\n[![NPM Package][npm-image]][npm-url] [![Github Actions][github-actions-image]][github-actions-url]\n\nChart.js module for charting maps with legends. Adding new chart types: `choropleth` and `bubbleMap`.\n\n![Choropleth](https://user-images.githubusercontent.com/4129778/78821942-8b974700-79da-11ea-988d-142f7788ffe6.png)\n\n[![Open in CodePen][codepen]](https://codepen.io/sgratzl/pen/gOaBQep)\n\n![Earth Choropleth](https://user-images.githubusercontent.com/4129778/78821946-8d610a80-79da-11ea-9ebb-23baca9db670.png)\n\n[![Open in CodePen][codepen]](https://codepen.io/sgratzl/pen/bGVmQKw)\n\n![Bubble Map](https://user-images.githubusercontent.com/4129778/78821935-89cd8380-79da-11ea-81bf-842fcbd3eff4.png)\n\n[![Open in CodePen][codepen]](https://codepen.io/sgratzl/pen/YzyJRvm)\n\nworks great with https://github.com/chartjs/chartjs-plugin-datalabels\n\n## Related Plugins\n\nCheck out also my other chart.js plugins:\n\n- [chartjs-chart-boxplot](https://github.com/sgratzl/chartjs-chart-boxplot) for rendering boxplots and violin plots\n- [chartjs-chart-error-bars](https://github.com/sgratzl/chartjs-chart-error-bars) for rendering errors bars to bars and line charts\n- [chartjs-chart-graph](https://github.com/sgratzl/chartjs-chart-graph) for rendering graphs, trees, and networks\n- [chartjs-chart-pcp](https://github.com/sgratzl/chartjs-chart-pcp) for rendering parallel coordinate plots\n- [chartjs-chart-venn](https://github.com/sgratzl/chartjs-chart-venn) for rendering venn and euler diagrams\n- [chartjs-chart-wordcloud](https://github.com/sgratzl/chartjs-chart-wordcloud) for rendering word clouds\n- [chartjs-plugin-hierarchical](https://github.com/sgratzl/chartjs-plugin-hierarchical) for rendering hierarchical categorical axes which can be expanded and collapsed\n\n## Install\n\n```bash\nnpm install --save chart.js chartjs-chart-geo\n```\n\n## Usage\n\nsee https://www.sgratzl.com/chartjs-chart-geo/ website\n\nCodePens\n\n- [Choropleth](https://codepen.io/sgratzl/pen/gOaBQep)\n- [Earth Choropleth](https://codepen.io/sgratzl/pen/bGVmQKw)\n- [Bubble Map](https://codepen.io/sgratzl/pen/YzyJRvm)\n\n## Options\n\nThe option can be set globally or per dataset\n\nsee [https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/controllers/GeoController.ts#L221](https://github.com/sgratzl/chartjs-chart-geo/blob/be3979117f8ae9a249969593c108d9b92b7e07fa/src/controllers/GeoController.ts#L225-L254)\n\n## Choropleth\n\nA Choropleth (chart type: `choropleth`) is used to render maps with the area filled according to some numerical value.\n\n![Choropleth](https://user-images.githubusercontent.com/4129778/78821942-8b974700-79da-11ea-988d-142f7788ffe6.png)\n\n[![Open in CodePen][codepen]](https://codepen.io/sgratzl/pen/gOaBQep)\n\n![Earth Choropleth](https://user-images.githubusercontent.com/4129778/78821946-8d610a80-79da-11ea-9ebb-23baca9db670.png)\n\n[![Open in CodePen][codepen]](https://codepen.io/sgratzl/pen/bGVmQKw)\n\n### Data Structure\n\nA data point has to have a `.feature` property containing the feature to render and a `.value` property containing the value for the coloring.\n\n[TopoJson](https://github.com/topojson) is packaged with this plugin to convert data, it is exposed as `ChartGeo.topojson` in the global context. However, this plugin doesn't include any topojson files itself. Some useful resources I found so far:\n\n- US map: https://www.npmjs.com/package/us-atlas\n- World map: https://www.npmjs.com/package/world-atlas\n- individual countries: https://github.com/markmarkoh/datamaps/tree/master/src/js/data (untested)\n- topojson collection: https://github.com/deldersveld/topojson (untested)\n\n```js\nconst us = await fetch('https://cdn.jsdelivr.net/npm/us-atlas/states-10m.json').then((r) =\u003e r.json());\n\n// whole US for the outline\nconst nation = ChartGeo.topojson.feature(us, us.objects.nation).features[0];\n// individual states\nconst states = ChartGeo.topojson.feature(us, us.objects.states).features;\n\nconst alaska = states.find((d) =\u003e d.properties.name === 'Alaska');\nconst california = states.find((d) =\u003e d.properties.name === 'California');\n...\n\nconst config = {\n  data: {\n    labels: ['Alaska', 'California'],\n    datasets: [{\n      label: 'States',\n      outline: nation, // ... outline to compute bounds\n      showOutline: true,\n      data: [\n        {\n          value: 0.4,\n          feature: alaska // ... the feature to render\n        },\n        {\n          value: 0.3,\n          feature: california\n        }\n      ]\n    }]\n  },\n  options: {\n    scales: {\n      projection: {\n        projection: 'albersUsa' // ... projection method\n      }\n    }\n  }\n};\n\n```\n\n### Styling\n\nThe styling of the new element `GeoFeature` is based on [Bar Element](https://www.chartjs.org/docs/latest/configuration/elements.html#bar-configuration) with some additional options for the outline and graticule.\n\nsee https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/elements/GeoFeature.ts#L41\n\n### Legend and Color Scale\n\nThe coloring of the nodes will be done with a special color scale. The scale itself is based on a linear scale.\n\nsee\n\n- https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/scales/LegendScale.ts#L148\n- https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/scales/ColorScale.ts#L180\n\n## Bubble Map\n\nA Bubble Map (chart type: `bubbleMap`) aka Proportional Symbol is used to render maps with dots that are scaled according to some numerical value. It is based on a regular `bubble` chart where the positioning is done using latitude and longitude with an additional `sizeScale` to create a legend for the different radi.\n\n![Bubble Map](https://user-images.githubusercontent.com/4129778/78821935-89cd8380-79da-11ea-81bf-842fcbd3eff4.png)\n\n[![Open in CodePen][codepen]](https://codepen.io/sgratzl/pen/YzyJRvm)\n\n### Data Structure\n\nsee [Bubble Chart](https://www.chartjs.org/docs/latest/charts/bubble.html#data-structure). Alternatively to `x` and `y`, the following structure can be used:\n\n```ts\ninterface IBubbleMapPoint {\n  longitude: number;\n  latitude: number;\n  value: number;\n}\n```\n\n**Note**: instead of using the `r` attribute as in a regular bubble chart, the `value` attribute is used, which is picked up by the `sizeScale` to convert it to an actual pixel radius value.\n\n### Styling\n\nA regular point is used and thus supports the [Point Element](https://www.chartjs.org/docs/latest/configuration/elements.html#point-configuration) styling options. In addition, the `outline*` and `graticule*` are supported.\n\n### Legend\n\nSimilar to the choropleth chart a new `sizeScale` is used to map the values to symbol radius size. The scale itself is based on a linear scale.\n\nsee\n\n- https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/scales/LegendScale.ts#L148\n- https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/scales/SizeScale.ts#L52\n\n## Scales\n\nA new scale `projection` is registered and used by default by Choropleth and BubbleMap. The available methods are the one from https://github.com/d3/d3-geo#projections. Just remove the `geo` prefix. Alternatively, the projection method instance can be directly given.\n\nsee https://github.com/sgratzl/chartjs-chart-geo/blob/main/src/scales/ProjectionScale.ts#L76\n\n### ESM and Tree Shaking\n\nThe ESM build of the library supports tree shaking thus having no side effects. As a consequence the chart.js library won't be automatically manipulated nor new controllers automatically registered. One has to manually import and register them.\n\nVariant A:\n\n```js\nimport { Chart } from 'chart.js';\nimport { ChoroplethController, GeoFeature, ColorScale, ProjectionScale } from 'chartjs-chart-geo';\n\n// register controller in chart.js and ensure the defaults are set\nChart.register(ChoroplethController, GeoFeature, ColorScale, ProjectionScale);\n\nconst chart = new Chart(document.getElementById('canvas').getContext('2d'), {\n  type: 'choropleth',\n  data: {\n    // ...\n  },\n});\n```\n\nVariant B:\n\n```js\nimport { ChoroplethChart } from 'chartjs-chart-geo';\n\nconst chart = new ChoroplethChart(document.getElementById('canvas').getContext('2d'), {\n  data: {\n    //...\n  },\n});\n```\n\n## Development Environment\n\n```sh\nnpm i -g yarn\nyarn install\nyarn sdks vscode\n```\n\n### Common commands\n\n```sh\nyarn compile\nyarn test\nyarn lint\nyarn fix\nyarn build\nyarn docs\n```\n\n[npm-image]: https://badge.fury.io/js/chartjs-chart-geo.svg\n[npm-url]: https://npmjs.org/package/chartjs-chart-geo\n[github-actions-image]: https://github.com/sgratzl/chartjs-chart-geo/workflows/ci/badge.svg\n[github-actions-url]: https://github.com/sgratzl/chartjs-chart-geo/actions\n[codepen]: https://img.shields.io/badge/CodePen-open-blue?logo=codepen\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgratzl%2Fchartjs-chart-geo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgratzl%2Fchartjs-chart-geo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgratzl%2Fchartjs-chart-geo/lists"}