Components/SankeyChart

SankeyChart

Flow diagrams on the d3-sankey layout: gradient links and draggable nodes.

VerifiedSince 0.1.0

Usage

nodes is the node array; links connect nodes by index (source/target index into nodes). Node color precedence: node.color > defaultNodeColor > the categorical palette by index. Links blend source → target colors by default; link-color="gray" switches to a flat gray. Value labels turn on automatically when any node carries a value (showNodeValues forces either way).

Traffic distribution

Gradient links + tooltip

Hover for value and tooltipData rows; drag a node to move it, drillable links get a pointer cursor.

Loading demo...

Inline labels + gray links

Small nodes read better with the inline 'value name' layout.

Loading demo...

API Reference

SankeyChart Props

PropTypeDefaultDescription
nodesSankeyNodeData[]—{ name, color?, value?, tooltipData?, isDrillable?, childCount? }.
linksSankeyLinkData[]—{ source, target, value, isDrillable? }, index references.
heightnumber400Pixel height.
widthnumbermeasuredExplicit width (SSR/tests).
nodeWidthnumber8Node bar width.
nodePaddingnumber10Vertical gap between nodes in a column.
showNodeValuesboolean | 'auto''auto''auto' enables labels when any node has a value.
nodeLabelLayout'stacked' | 'inline''stacked'Value above the name / on one line.
formatValue(v: number) => stringtoLocaleStringValue formatter.
showTooltipbooleantrueHover tooltip.
defaultNodeColorstring—Fallback before the categorical palette.
leftnumber | string'5%'Left layout inset (px or percent).
rightnumber | string'5%'Right layout inset (px or percent).
linkColor'gradient' | 'gray''gradient'Link fill mode.
linkOpacitynumber0.5Gradient link opacity.
labelsPartial<SankeyLabels>English{ instructions, value, items }: instructions is read after each node's name; value names the tooltip's value row and items counts a drillable node's items.

SankeyChart Events

EventPayloadDescription
node-click(node: SankeyNodeData)Node clicked; the original datum.
link-click(link: SankeyLinkData)Link clicked; the original datum.

SankeyChart Slots

SlotScopeDescription
tooltip{ params: SankeyTooltipParams }Replaces the tooltip body; params.type is 'node' | 'link'.

Node Dragging

Nodes move vertically. Each stays in its column and its links re-route live.

InputEffect
Drag a nodeFollows the pointer 1:1 from where it was grabbed, inside the chart's height. Past 4 px the press never fires node-click.
ReleaseThe node stays where it was dropped.
Escape during a dragCancels; the node springs back to where it was picked up.
Double-click the backgroundSprings every node back to the computed layout.
Alt + ↑ / ↓ on a focused nodeMoves it 8 px.
Enter / Space on a focused nodeSelects it (node-click).

Nodes take focus (role="button", named by the node) and read labels.instructions after the name; it merges over SANKEY_DEFAULT_LABELS. A touch drag that starts on a node moves it instead of scrolling the page; a touch on a link or the background still scrolls. Different nodes (names, values), links (ends, values) or height start over from the computed layout and drop every move; a new array with the same content keeps them. Under prefers-reduced-motion: reduce the springs jump to their end state; a dragged node still follows the pointer.

Resilience

Circular links make d3-sankey throw — the component catches that, renders an empty state and logs a dev warning instead of crashing the host page.

Hover Highlight

Hovering a node or a link leaves only adjacent elements untouched: the non-adjacent nodes, links and labels dim together to 10% opacity, matching ECharts' emphasis.focus: 'adjacency' (blur is fromState.opacity * 0.1), switched on the frame the pointer arrives rather than over ECharts' 300ms cubicOut (TuffEx's hover rule). A node's neighbourhood is itself, every link touching it and the nodes at those links' other ends; a link's is itself, its two endpoint nodes and every link touching either endpoint.

Sankey has no geometry animation when the data changes, which is parity with kumo rather than a missing feature: ECharts' SankeyView has neither initProps nor updateProps, so when the d3-sankey layout changes the nodes and links land on their new positions without a tween. Only the drag's own springs (Escape, reset) move. Under prefers-reduced-motion: reduce the 300ms transition drops out and the highlight switches instantly.

Differences from kumo

  • tooltipFormatter (HTML strings + manual XSS escaping) → the tooltip slot (VNodes).
  • kumo's nodes are fixed; here a node can be dragged, nudged with Alt + arrow keys and reset.
  • kumo throws on circular input; this degrades to an empty render with a dev warning.