Sankey Chart
Sankey chart for flows between stages: basic and gradient flows, a vertical sankey, an alluvial and a chord diagram.
Playground
Installation
Sankey Chart comes with WunderUI Core and Pro, in the package from your plan. See the plans.
The charts live in their own entry point: import the chart, its card and its hooks from @wunderui/react/charts, not from @wunderui/react.
Then import what you need:
import {
SankeyChart,
SankeyChartProps,
SankeyChartVariant,
} from "@wunderui/react/charts"Then use it:
import { SankeyChart } from "@wunderui/react/charts"
const nodes = [{ id: "Search" }, { id: "Docs" }, { id: "Signup" }]
const links = [
{ source: "Search", target: "Docs", value: 3200 },
{ source: "Docs", target: "Signup", value: 1300 },
]
export function TrafficFlow() {
return <SankeyChart nodes={nodes} links={links} label="Traffic to signups" />
}Expected result: You see three nodes in a row joined by two ribbons, the first wider than the second.
When to use
Use Sankey Chart for
- Quantities that flow between stages: traffic to pages to signups
- Moves between states over time (alluvial)
- Flows in both directions between a few places (chord)
Use something else for
- Funnel Chart for a count that drops through ordered stages
- Network Chart for relations without quantities
- Waterfall Chart for changes that add up to a total
- Treemap for parts of a hierarchy
States
Loading, empty and error keep the chart's size, so the card never jumps. Add a retry handler and the error state offers a Try again button.
Keyboard interactions
The plot is focusable and arrow keys walk the flows, then the nodes. A flow reads like Free to Pro: 18, 18% of Free, and a node reads its totals in and out.
- TaborShiftTab
- Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge.
- ArrowRightorArrowLeft
- Moves to the next or previous flow. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one).
- HomeorEnd
- Jumps to the first or last flow.
- Escape
- Clears the active point.
- EnterorSpace
- On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on.
Behavior and motion
What the chart does on its own and what the page decides.
- Nodes and links
- Nodes list the stages and links list the flows between them. Links to unknown nodes, self loops and zero or invalid values are dropped before layout.
- Groups
- Groups set the legend order and colours, and nodes of one group share a colour. Hidden series fade the flows of a group or node.
- Alluvial
- Columns name the stages of an alluvial chart, one per time step, and nodes are coloured by their state.
- Hover
- A hovered flow stays and the others dim. The tooltip shows its value and its share of the source node's outflow.
- Loading, empty and error
- The chart keeps its size while loading, empty or failed, so the card never jumps. Add a retry handler to show a Try again button on error.
- Legend
- A ChartCard shows the series as badges. With two or more series each badge switches its series off, but the last visible one stays on.
- Size
- The chart fills the width of its container, and you set the plot height. Text never scales, so labels keep their size at every width.
Motion
The enter sequence and the hover follow the library's motion tokens.
- Draw-in
- Bars and ribbons are drawn along their path when the chart first comes into view, after loading and when the data changes. You can turn it off.
- Reduced motion
- With reduced motion the chart appears at once. The tooltip, the crosshair and every state still work.
Anatomy
A Sankey chart shows quantities flowing between stages. It covers basic, gradient, vertical, alluvial and chord layouts, drawn with widths proportional to the value.
Traffic flow
| Source → target | Flow | Share of source |
|---|---|---|
| Search → Docs | 3.2k | 78% |
| Search → Pricing | 0.9k | 22% |
| Direct → Pricing | 1.6k | 64% |
| Direct → Docs | 0.9k | 36% |
| Pricing → Signup | 1.9k | 76% |
| Pricing → Left | 0.6k | 24% |
| Docs → Signup | 1.3k | 32% |
| Docs → Left | 2.8k | 68% |
| Node | In | Out |
|---|---|---|
| Search | – | 4.1k |
| Direct | – | 2.5k |
| Pricing | 2.5k | 2.5k |
| Docs | 4.1k | 4.1k |
| Signup | 3.2k | – |
| Left | 3.4k | – |
Takes the nodes and the links between them. Optional props caption the stages of an alluvial, set the legend order and colours, and fade the flows of a group.
- data-slot="chart-plot"
The focusable region. Arrow keys walk its marks and a live region reads each one the way the tooltip shows it.
- data-slot="chart-marks"
Node bars and flow ribbons whose widths show the values, with the other flows dimmed on hover. The chord variant draws arcs around a circle.
A label beside each node, shortened to the room that is left. Nodes of one group share a colour.
- data-slot="chart-tooltip"
The value of the flow under the pointer and its share of the source node's outflow.
- data-slot="chart-message"
Muted bars, or a muted ring on a chord chart, under the shimmer. Links to unknown nodes, self loops and zero or invalid values are dropped.
A hidden table with one row per flow.
Best practices
- Do
Keep it to about ten nodes and three or four stages. More crossing ribbons turn into a tangle nobody can follow.
- Do
Colour by group so a ribbon keeps the colour of where it starts, and name the groups in the legend.
- Do
Make the flows into a node add up to the flows out of it. Unbalanced nodes are drawn at the larger side, which hides the gap.
- Don’t
Don't use the chord variant for one-way flows: it is for flows in both directions between the same items. Use a sankey for stages.
- Don’t
Don't rely on ribbon width for small values. Thin flows need the tooltip or the table, so put the key numbers in the card.
API reference
One table for SankeyChart, listing every prop. The ChartCard around it has its own props, and the chart also works without one.
Takes the nodes and the links between them. Optional props caption the stages of an alluvial, set the legend order and colours, and fade the flows of a group.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("sankey-chart")The full library index for assistants is at /llms.txt.