ztd chartsHome

Map · Intermediate

Symbol map

One circle per place on a pale map, its area proportional to the value.

Open in playground
Use when
Amounts that sit at a point, such as users per city, revenue per store or traffic per data centre, where absolute sizes should compare directly
Avoid when
The value is a rate across a whole region (use choropleth), or the places are so many and so close that circles cover each other (aggregate first)

Try it

43

Symbol map

Monthly active users by city
Tokyo leads with 15% of usersIntermediate

Hover over the chart, or Tab in and use the arrow keys to move between items. The numbers are sample data.

Variants

Named looks for this chart. Each one is the example above with a few options or fields changed. The CLI (ztd-charts example symbolMap --variant <id>) and the MCP server know the same names.

Colored by continent

Sample data

Countries without coordinates

Sample data

US stores

Sample data

Europe

Sample data

South Korea

Sample data

Code

SymbolMap.tsx
import { ChartCard, SymbolMap } from "ztd-charts";

const data = [
  {"city":"Tokyo","continent":"Asia","lon":139.69,"lat":35.69,"users":1180000},
  {"city":"São Paulo","continent":"Americas","lon":-46.63,"lat":-23.55,"users":820000},
  {"city":"Jakarta","continent":"Asia","lon":106.85,"lat":-6.21,"users":710000},
  {"city":"New York","continent":"Americas","lon":-74.01,"lat":40.71,"users":640000},
  {"city":"Mumbai","continent":"Asia","lon":72.88,"lat":19.08,"users":600000},
  {"city":"London","continent":"Europe","lon":-0.13,"lat":51.51,"users":560000},
  // … 9 more rows
];

export function Example() {
  return (
    <ChartCard number="43" title="Symbol map" subtitle="Monthly active users by city" takeaway="Tokyo leads with 15% of users" level="intermediate" replay>
      <SymbolMap
        data={data}
        size="users"
        label="city"
        format="compact"
      />
    </ChartCard>
  );
}

Props

<SymbolMap> takes these props. Rows marked Common work the same on every chart.

35 props

Prop
dataRequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]
lonLongitude (degrees)string | (d, i) => number
latLatitude (degrees)string | (d, i) => number
sizeValue (circle area). Without it all circles matchstring | (d, i) => number
labelPlace namestring | (d, i) => string
regionRegion of options.map, for rows without lon and latstring | (d, i) => string
groupGroup field (one color per group)string | (d, i) => string
mapBase map. "auto" picks the registered map that takes the most places (coordinates inside it or region names on it), and the narrower map on a tie, so US cities land on "us-states". "world", "us-states", "kr-sido" or a GeoJSON FeatureCollection, as for choropleth. Points outside the drawn frame are left out and reportedanyDefault "auto"
focusShow only part of the world map, cropped and enlarged. Places outside it are left out"europe" | "asia" | "africa" | "americas" | "oceania"
featureIdGeoJSON property that holds the region idstring
featureNameGeoJSON property that holds the region namestring
sizeRangeCircle radius range [smallest, largest] in px. By default it follows the width. The largest radius is capped at an eighth of the chart's shorter sidenumber[]
centerCentre of the world map. "auto" picks the view that pushes the fewest places to the edge; "atlantic" centres longitude 0, "pacific" centres longitude 150 and cuts the map in the Atlantic. Not used with focus or other maps"auto" | "atlantic" | "pacific"Default "auto"
legendShow the size legend (two or three reference circles)booleanDefault true
heightCommonHeight in px. Without it, each chart picks a default that fits its widthnumber
widthCommonFixed width in px. Without it, the chart fits its parentnumber
highlightCommonItem to highlight. An index, a name, an array, or "max" | "min" | "first" | "last" | "none"number | string | (number|string)[] | "max" …
formatCommonValue format. "number" | "integer" | "percent" (values are already percents: 42 → "42%") | "ratio" (0.42 → "42%") | "compact" | "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) | "decimal" or Intl.NumberFormat options"number" | "percent" | "compact" | …
unitCommonUnit appended to values. For example "%" or "ms"string
localeCommonLocale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider localestringDefault "en-US"
animateCommonEntry and update animationbooleanDefault true
durationCommonAnimation length (ms)number
easingCommonMotion curve"spring" | "easeOut" | "easeInOut" | "linear"Default "spring"
staggerCommonDelay between items as they enter (ms)number
reducedMotionCommon"auto" follows the OS setting. true always turns motion offanyDefault "auto"
animateOnViewCommonPlay when the chart scrolls into viewbooleanDefault true
showLabelsCommonLabels drawn on the chart (values and names)booleanDefault true
tooltipCommonShow tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left outtooltipDefault true
syncIdCommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside itstring
ariaLabelCommonName for screen readersstring
descriptionCommonDescription for screen readers. Built from the data when omittedstring
onHoverCommonRuns when hover or keyboard focus moves to another item(e: ChartEvent | null) => void
onClickCommonRuns on click, Enter or Space(e: ChartEvent) => void
replayKeyCommonReplays the entry animation when it changesstring | number
themeCommonChanges theme tokens for this chart onlyPartial<ChartTheme>

Also in Map