SankeyChart
Flow diagrams on the d3-sankey layout: gradient links, node value labels, drill affordances and slot tooltips.
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 nodes for value and tooltipData rows; drillable nodes get a pointer cursor.
Inline labels & gray links
Inline labels + gray links
Small nodes read better with the inline 'value name' layout.
API Reference
SankeyChart Props
| Prop | Type | Default | Description |
|---|---|---|---|
nodes | SankeyNodeData[] | — | { name, color?, value?, tooltipData?, isDrillable?, childCount? }. |
links | SankeyLinkData[] | — | { source, target, value, isDrillable? }, index references. |
height | number | 400 | Pixel height. |
width | number | measured | Explicit width (SSR/tests). |
nodeWidth | number | 8 | Node bar width. |
nodePadding | number | 10 | Vertical gap between nodes in a column. |
showNodeValues | boolean | '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) => string | toLocaleString | Value formatter. |
showTooltip | boolean | true | Hover tooltip. |
defaultNodeColor | string | — | Fallback before the categorical palette. |
left / right | number | string | '5%' | Layout insets (px or percent). |
linkColor | 'gradient' | 'gray' | 'gradient' | Link fill mode. |
linkOpacity | number | 0.5 | Gradient link opacity. |
SankeyChart Events
| Event | Payload | Description |
|---|---|---|
node-click | (node: SankeyNodeData) | Node clicked; the original datum. |
link-click | (link: SankeyLinkData) | Link clicked; the original datum. |
SankeyChart Slots
| Slot | Scope | Description |
|---|---|---|
tooltip | { params: SankeyTooltipParams } | Replaces the tooltip body; params.type is 'node' | 'link'. |
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 over 300ms cubicOut. 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, 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. Under prefers-reduced-motion: reduce the 300ms transition drops out and the highlight switches instantly.
Differences from kumo
tooltipFormatter(HTML strings + manual XSS escaping) → thetooltipslot (VNodes).- kumo throws on circular input; this degrades to an empty render with a dev warning.