Map chart
A choropleth and point map on vector outlines, drawn by ECharts: regions shaded by a value, with layers of sized points and flow lines, on the bundled world and US maps or your own GeoJSON, TopoJSON or SVG.
The figures in these examples are illustrative, not real company or market data. The outlines are real: Natural Earth’s countries and the US Census Bureau’s states.
Import
import '@c2n/components/chart/map-chart'This chart draws with ECharts, a peer dependency it loads on first draw: npm install echarts.
Usage
region-field names each row’s region and value-field holds the value it is shaded by. Rows join regions on the map’s region key:
| Map | Default region-key | Other keys |
|---|---|---|
world-110m (the default, about 105 KB) | iso_a3, ISO 3166-1 alpha-3 (BRA) | iso_a2, id (the numeric code, 076), name |
world-50m (about 750 KB, for zoomed-in maps and small islands) | iso_a3 | iso_a2, id, name |
us-states (the 50 states and DC, about 115 KB) | postal, the USPS code (CA) | id (the FIPS code, 06), name |
Each map is a separate module that loads the first time a chart names it. A key that differs only in case still matches (fra finds France). Rows that name no region are skipped and reported once by the unmatched-rows event, so a typo in the data shows up in the console of whoever listens rather than as a silently blank country. A region without a row keeps --c2-chart__region--background-color and appears as No data in the colour key. The world maps leave Antarctica out.
Scales
scale="sequential" (the default) shades from --c2-chart__scale-start--color to --c2-chart__scale-end--color across the data’s extent; domain="[0, 5000]" pins the ends so several maps can be compared. scale="diverging" runs from --c2-chart__scale-negative--color through --c2-chart__scale-mid--color to the end colour, around a midpoint of 0 with a symmetric range, so the same distance from zero is equally strong on both sides; domain="[min, mid, max]" moves it.
thresholds turns either scale into stepped classes: [-10, -5, -2, 2, 5, 10] makes seven, and a value equal to a break falls in the upper one. Classes are easier to read off a legend than a gradient. scale-colors gives one colour per class and scale-labels names them, as in the data hall card of the gallery. Colours are mixed in OKLab, so the middle of a ramp is not muddier than its ends.
unit is appended to every value in the tooltip and the key (%, °C); format is the property for anything else.
Layers
c2-map-layer children draw on top of the regions, each with its own data and one entry in the legend:
type="points"places a circle atlon-field/lat-field(lonandlatby default), or at the region named byregion-field, which uses the centroid of the region’s largest shape.size-fieldsizes it by area, between--c2-chart__marker--min-sizeand--max-size; larger points are drawn first so the small ones stay hoverable.labelswrites thelabel-fieldbeside each point.type="lines"draws fromfrom-fieldtoto-field, each a region key or a[lon, lat]pair.curve="geodesic"(the default) follows the shortest path over the globe and is split where it crosses the date line;arcdraws a gentle curve andstraighta segment on the drawn map.width-fieldsets the stroke width up to--c2-chart__flow--max-width.
legend-action="toggle" lets the legend hide a layer; the default highlights it and fades the others, as a click on one of its marks does.
Projections and extent
projection defaults to the map’s own: Equal Earth for the world maps, which keeps every country’s area true, Albers USA (with Alaska and Hawaii inset) for us-states, Mercator for your own GeoJSON. natural-earth, equirectangular and mercator are the alternatives.
extent fits the view to part of the map: region keys (extent="FRA DEU ITA"), a named area (europe, africa, asia, middle-east, north-america, south-america, oceania), or a [west, south, east, north] box in degrees. The rest of the map stays drawn around it.
roam="zoom" adds zoom buttons and lets a zoomed map be dragged; roam="pan" allows dragging only; roam="both" adds the mouse wheel and pinch, which then no longer scroll the page, so it suits a map that fills its view. max-zoom caps the zoom (8 by default). zoomIn(), zoomOut() and resetView() drive the same view from script, and view-change reports the visible area in degrees.
Selecting regions
selection="single" or "multiple" makes a click select a region, outlined by --c2-chart__region__selected--border-color. The map is then a form control: value holds the selected keys (as an attribute, separated by semicolons), a form receives one name entry per region, and selection-change, input and change fire after each click. point-click fires first and is cancelable: preventDefault() keeps the selection as it is, which is how an application limits the selectable regions.
Your own geometry
geo (a property) takes a GeoJSON FeatureCollection, an array of features, a TopoJSON topology (its first object is drawn) or SVG markup; src loads any of them from a URL. Both win over map. A GeoJSON region joins on id unless region-key names a property.
“Vector map” is not only geography. In an SVG, every shape or group with an id is a region (its data-name or <title> names it in the tooltip); projection is then none and a point layer’s longitude and latitude are x and y in the SVG’s own coordinates. Floor plans, seat maps and machine diagrams work the same way as countries.
Borders and attribution
The world outlines are Natural Earth’s 1:110m and 1:50m countries, in the public domain, through world-atlas; the states come from the US Census Bureau’s cartographic boundaries through us-atlas. Natural Earth draws the boundaries in effect on the ground, not any one government’s claim. A product that has to show an official view should pass its own outlines through geo rather than edit the bundled data.
Styling
Regions are styled through --c2-chart__region… (fill without data, borders, the hovered and selected outlines), the scale through --c2-chart__scale…, points through --c2-chart__marker…, lines through --c2-chart__flow… and the zoom buttons through --c2-chart__zoom-control…. Layer colours come from --c2-chart__series-1…8--color as on every chart, or each layer’s color.
Accessibility
A map is colour on shapes, which a screen reader cannot read. The chart renders the joined rows as a visually hidden table (region and value), and every value in the tooltip and key is text in the chart’s text colour, never in the scale colour. The zoom buttons are real buttons with labels. Selecting regions from the keyboard is not supported yet: an application that needs it should offer a list of the same regions next to the map.