ztd chartsHome

Map · Advanced

Flow map

Curved links between places on a map, their width proportional to the amount.

Open in playground
Use when
From where to where and how much: shipments, migration, transfers or traffic between regions, where direction and distance matter
Avoid when
Only the amounts matter and places have no meaningful position (use sankey or chord), or there are hundreds of crossing flows

Try it

44

Flow map

Container shipments between ports (TEU)
Shanghai to LA is the top laneAdvanced

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 flowMap --variant <id>) and the MCP server know the same names.

Between US states

Sample data

Europe

Sample data

South Korea

Sample data

Without the ranked list

Container shipments between ports (TEU)
Sample data

Code

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

const data = [
  {"from":"Shanghai","to":"Los Angeles","teu":412000},
  {"from":"Shanghai","to":"Rotterdam","teu":268000},
  {"from":"Singapore","to":"Rotterdam","teu":231000},
  {"from":"Busan","to":"Los Angeles","teu":205000},
  {"from":"Shanghai","to":"Singapore","teu":174000},
  {"from":"Singapore","to":"Dubai","teu":140000},
  // … 5 more rows
];

export function Example() {
  return (
    <ChartCard number="44" title="Flow map" subtitle="Container shipments between ports (TEU)" takeaway="Shanghai to LA is the top lane" level="advanced" replay>
      <FlowMap
        data={data}
        source="from"
        target="to"
        value="teu"
        places={{"Shanghai":[121.47,31.23],"Singapore":[103.82,1.35],"Rotterdam":[4.48,51.92],"Los Angeles":[-118.24,34.05],"Busan":[129.08,35.18],"Dubai":[55.27,25.2],"New York":[-74.01,40.71],"Santos":[-46.33,-23.96],"Hamburg":[9.99,53.55]}}
        format="compact"
      />
    </ChartCard>
  );
}

Props

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

32 props

Prop
dataRequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]
sourceRequiredStart: a name in options.places or a regionstring | (d, i) => string
targetRequiredEndstring | (d, i) => string
valueAmount. Without it each row counts 1string | (d, i) => number
placesWhere each place is: { name: [longitude, latitude] } in degrees. Names that are not here are matched to a region of the map (a country, a state) and placed at its centreobject
mapBase map. "auto" picks the registered map that takes the most places, and the narrower map on a tie. "world", "us-states", "kr-sido" or a GeoJSON FeatureCollection, as for choroplethanyDefault "auto"
focusShow only part of the world map, cropped and enlarged. Flows to 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
rankingRanked list of the largest flows beside the map. "auto" shows it when the chart is at least 600px wideanyDefault "auto"
centerCentre of the world map. "auto" picks the view that cuts the least flow volume at the map edge, so trans-Pacific lanes get a Pacific-centred map; "atlantic" centres longitude 0, "pacific" centres longitude 150 and cuts the map in the Atlantic. A flow that still crosses the edge gets matching arrowheads where it leaves and re-enters. Not used with focus or other maps"auto" | "atlantic" | "pacific"Default "auto"
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