Chord chart
Flows between groups around a circle, where one row is one flow from a source to a target.
A chord diagram shows how much moves between a set of groups: money between currency wallets, customers
between products, orders from quarters to countries. One row is one flow, read through source-field,
target-field and value-field. Each group is an arc whose length is everything that leaves and reaches it,
and each flow is a ribbon between two arcs, as wide as the flow. Rows for the same pair are summed. It is drawn
by ECharts’ chord series, so hovering an arc lights up the ribbons it touches.
Import
import '@c2n/components/chart/chord-chart'This chart draws with ECharts 6, a peer dependency it loads on first draw: npm install echarts.
Usage
Data
Rows are plain objects, and the three fields may be dotted paths. A row is left out when it has no source or no target, when its value is not a positive number, or when it flows from a group to itself: none of those can be drawn as a ribbon. Two flows between the same groups in opposite directions are two ribbons, and the tooltip of either shows both.
The groups and flows getters return what the chart drew (each group’s outgoing, incoming and total, each
flow with its reverse), for a table beside the chart or an export. buildChordModel(rows, options) is the same
computation as a plain function.
Layout and order
layout="circle" (the default) places the groups in the order they first appear, starting at twelve o’clock.
layout="bipartite" is for flows between two different kinds of thing: the groups that send go on the right
half and the groups that only receive go on the left, reversed so that the two sides face each other. sort
(asc or desc) orders the groups by their total; in a bipartite layout each side is sorted on its own.
Colour
Each group takes the next colour of --c2-chart__series-1…8--color in order of first appearance, and keeps it
when the groups are sorted or one is hidden. ribbon-color decides which end of a flow its ribbon shows:
source (the default) makes it easy to follow where something went, target where it came from, and
gradient blends the two.
Interaction
Hovering an arc emphasises it and its ribbons and fires group-hover; hovering a ribbon fires ribbon-hover.
Clicking an arc fires group-click and highlights the group (its key goes to highlighted and
series-highlight fires), dimming the ribbons it does not touch; a second click clears it, and
preventDefault() on group-click keeps the highlight as it is. Clicking a ribbon fires ribbon-click.
The labels already name every group, so the legend is off by default. With legend="bottom" and
legend-action="toggle", an entry hides its group and every flow that touches it (setGroupVisible(key, false) does the same from code); the last two groups stay on.
The plot is one tab stop: the arrow keys move between groups and announce their totals, Enter highlights the focused group and Escape clears. A visually hidden table lists every flow for screen readers.
Styling
--c2-chart__arc--width sets the thickness of the arcs (12px), --c2-chart__arc--gap the gap between them in
degrees (3), and --c2-chart__ribbon--opacity and --c2-chart__ribbon__hover--opacity how strongly the
ribbons show at rest and under the pointer. labels="none" hands the room the labels took back to the circle.