# Sankey Chart

Sankey chart for flows between stages: basic and gradient flows, a vertical sankey, an alluvial and a chord diagram.

- Category: Charts
- Page: https://wunderui.com/components/sankey-chart
- Tier: Core and Pro

## Install

Sankey Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { SankeyChart, SankeyChartProps, SankeyChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
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

- [Funnel Chart](https://wunderui.com/components/funnel-chart) for a count that drops through ordered stages
- [Network Chart](https://wunderui.com/components/network-chart) for relations without quantities
- [Waterfall Chart](https://wunderui.com/components/waterfall-chart) for changes that add up to a total
- [Treemap](https://wunderui.com/components/treemap) for parts of a hierarchy

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | 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). |
| `Home` or `End` | Jumps to the first or last flow. |
| `Escape` | Clears the active point. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

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:** Node bars open from their middle and the flows draw along their path when the chart first comes into view, after loading and when the data changes; a parent re-render with the same data does not replay it. The chord ring blooms first and the ribbons unfold from the centre after it. You can turn it off.
- **Hover:** The flow or node in focus keeps its strength and the rest dims to --chart-dim. The layout is computed once per size, so moving the pointer stays smooth.
- **Reduced motion:** With reduced motion the enter sequence is off and the chart appears at once. The tooltip, the hover dimming and every state still work.

## Anatomy

- `SankeyChart`: 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.
- `Plot`: The focusable region. Arrow keys walk its marks and a live region reads each one the way the tooltip shows it.
- `Marks`: Node bars and flow ribbons whose widths show the values. Hovering a flow keeps it and its two nodes; hovering a node keeps its flows and neighbours; the rest dims. The chord variant draws arcs around a circle with ribbons between them.
- `Node labels`: A label beside each node, shortened to the room that is left. Nodes of one group share a colour.
- `Tooltip`: The value of the flow under the pointer and its share of the source node's outflow.
- `Loading, empty and error`: 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.
- `Data table and live region`: A hidden table with one row per flow.

## Best practices

### When to use

- Use it for flow between stages, such as channel to plan to outcome. For one-way drop-off use FunnelChart, and for a simple breakdown use PieChart.

### Do

- Keep it to about ten nodes and three or four stages. More crossing ribbons turn into a tangle nobody can follow.
- Colour by group so a ribbon keeps the colour of where it starts, and name the groups in the legend.
- 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 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

### SankeyChart

| Prop | Type | Default | Description |
|---|---|---|---|
| links* | readonly FlowLink[] |  |  |
| nodes* | readonly FlowNode[] |  |  |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  |  |
| animationKey | string \| number |  |  |
| className | string |  | Extra classes for the root element of the chart. |
| columns | readonly string[] |  | `alluvial`: captions under the columns (stages), e.g. ["Q1", "Q2", "Q3"]. |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| description | string |  |  |
| groups | readonly { key: string; label?: string; color?: ChartColor }[] |  | Groups in legend order with colours (default: in node order, palette colours). |
| height | number |  |  |
| hiddenSeries | readonly string[] |  | Group / node labels switched off in the legend: their flows fade. |
| label | string |  |  |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "basic-sankey" \| "gradient-sankey" \| "vertical-sankey" \| "alluvial" \| "chord" | "basic-sankey" | Figma variant. Default `basic-sankey`. |
| width | number |  |  |

## Examples

### States

## In context

### Plan Moves

Where accounts move between plans, with the quarter's numbers.

## For AI agents

`get_component("sankey-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
