Choropleth
A choropleth shades each region by a number. The shape is the place. The color is the value. A country, a state, or another area in the atlas gets a fill from encoding.color.
When to use it
Use a choropleth when the question is how a measure varies across places, and each place is a region you can name. Renewable share of electricity is one number per country. Population change, 2020–2023 is one number per state, and the scale diverges around zero.
A heatmap is a grid. The two axes are categories or time, and the cell color is the value. It has no coastline and no atlas. Use a heatmap when the axes are not places.
Map points put a mark at a latitude and longitude. Use that chart when the place is a point, not a region you can fill. A scatter is also points, and both axes are quantities. A choropleth has neither axis.
Data
One row per region. encoding.region is the column of names or codes. The atlas matches those strings: a country name, an ISO code, or a US postal abbreviation. encoding.color is the number that paints the region. A string field name is enough. An object can set field, format, and title.
A region with no row is no data. The default paint is a hatch. mark.nodata "fill" paints those regions with the land color instead. Set that in the playground. location is an alias of region.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest choropleth. version, type, and a11y.alt are required. Two countries and a world atlas. mark.scale is omitted, so the ramp is sequential. There is no tile layer, and no pan or zoom.
{
"version": "1",
"type": "choropleth",
"data": [
{
"country": "Norway",
"share": 98
},
{
"country": "France",
"share": 26
}
],
"encoding": {
"region": "country",
"color": "share"
},
"mark": {
"atlas": "world"
},
"a11y": {
"alt": "Norway is higher than France."
}
}Install @chartkitdev/geo. Maps are not in @chartkitdev/core, and the framework adapters do not draw them. render from the geo package is async. spec is the JSON above.
import { render, validate } from "@chartkitdev/geo";
const checked = validate(spec);
const svg = await render(spec);render from @chartkitdev/core does not draw this type. Core validate() warns CK3057 and leaves the atlas, the region field, and the value field to the geo package. Call validate from @chartkitdev/geo. Its warnings are CK3050 through CK3056, and the SVG still draws.
Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.
Examples
The rail switches between the two choropleth maps already published for this type. Renewable share of electricity is the world atlas and a sequential scale. Population change, 2020–2023 is the US atlas and a diverging scale. Both keep the size written on the spec.
Atlas
mark.atlas is world, us, canada, or eu. Omit it and the map is the world. The US atlas pairs with mark.projection albersUsa, which puts Alaska and Hawaii in insets. World, Canada, and the EU pair with equalEarth. This control writes that pair.
{
"mark": { "atlas": "us", "projection": "albersUsa" }
}The region keys have to exist in the atlas you pick. Renewable share of electricity uses country codes. Switching that example to us draws the states and hatches them, because those rows are not postal codes. Population change uses postal abbreviations, so the world atlas does not match them.
mercator, equirectangular, and fit are projections too. Set those in the playground. Pass mark.geojson or mark.topojson there when the place is not one of the four atlases. There are no US counties and no NUTS-2.
Scale
mark.scale is how the number becomes a color. Omit it, or set sequential, and the ramp runs from low to high in one hue. diverging is for a signed measure with a midpoint. Population change, 2020–2023 uses it: loss and gain sit on opposite sides of zero. threshold bins the values. Omit mark.thresholds and the bins are thirds of the data.
{
"mark": { "scale": "diverging" }
}encoding.color.range replaces the sequential ramp with your own stops. A diverging chart does not take that range. encoding.color.format formats the legend. Renewable share of electricity uses "%". Set a custom range or explicit thresholds in the playground.
Legend
The color legend is on when the scale has stops. Omit legend and it sits on the right. legend.position "bottom" moves it under the map. "right" is the other side this chart draws. top, left, and inside are not drawn.
{
"legend": { "position": "bottom" }
}{
"mark": { "legend": false }
}Off writes mark.legend: false. That is the key that hides the legend. legend: false does not. The map still draws the legend on the right.
Tooltip
On the other charts, omit tooltip and the hover card is on. tooltip: false turns that card off. tooltip: true turns it on. This control writes the same keys, so a spec you carry to those charts behaves the same way.
{
"tooltip": false
}{
"tooltip": true
}@chartkitdev/geo does not read tooltip: false yet. The region title stays in the SVG, and attach() from that package still shows it. Off updates the snippet. It does not remove the title. Turning the control back on deletes an omitted tooltip, or puts a tooltip object back if the example had one. Neither published choropleth sets tooltip.fields. Add extra hover columns in the playground, with tooltip.fields or encoding.tooltip.
The rest of the spec
mark.land and mark.water take a #rrggbb color. mark.nodata is hatch unless you set fill. Theme presets live on the playground. Population change, 2020–2023 is the midnight theme because that published spec sets it. This page does not add a theme control.