Skip to content
WunderUI

Sankey Chart

Pro

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

Playground

Traffic flow

Traffic from channels to signups: 15 flows between 9 nodes. Largest: Docs → Left 3.5k, Search → Docs 3.2k, Blog → Left 2.8k.
Traffic from channels to signups, data table
Source → targetFlowShare of source
Search → Docs3.2k54%
Search → Blog1.8k31%
Search → Pricing0.9k15%
Direct → Pricing1.6k64%
Direct → Docs0.9k36%
Social → Blog1.4k82%
Social → Pricing0.3k18%
Referral → Docs0.7k58%
Referral → Pricing0.5k42%
Pricing → Signup1.9k58%
Pricing → Left1.4k42%
Docs → Signup1.3k27%
Docs → Left3.5k73%
Blog → Signup0.4k13%
Blog → Left2.8k88%
Traffic from channels to signups, node totals
NodeInOut
Search–5.9k
Direct–2.5k
Social–1.7k
Referral–1.2k
Pricing3.3k3.3k
Docs4.8k4.8k
Blog3.2k3.2k
Signup3.6k–
Left7.7k–

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:

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

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 for

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.

Traffic flow

Traffic from channels to signups: 15 flows between 9 nodes. Largest: Docs → Left 3.5k, Search → Docs 3.2k, Blog → Left 2.8k.
Traffic from channels to signups, data table
Source → targetFlowShare of source
Search → Docs3.2k54%
Search → Blog1.8k31%
Search → Pricing0.9k15%
Direct → Pricing1.6k64%
Direct → Docs0.9k36%
Social → Blog1.4k82%
Social → Pricing0.3k18%
Referral → Docs0.7k58%
Referral → Pricing0.5k42%
Pricing → Signup1.9k58%
Pricing → Left1.4k42%
Docs → Signup1.3k27%
Docs → Left3.5k73%
Blog → Signup0.4k13%
Blog → Left2.8k88%
Traffic from channels to signups, node totals
NodeInOut
Search–5.9k
Direct–2.5k
Social–1.7k
Referral–1.2k
Pricing3.3k3.3k
Docs4.8k4.8k
Blog3.2k3.2k
Signup3.6k–
Left7.7k–

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

Traffic from channels to signups: 8 flows between 6 nodes. Largest: Search → Docs 3.2k, Docs → Left 2.8k, Pricing → Signup 1.9k.
Traffic from channels to signups, data table
Source → targetFlowShare of source
Search → Docs3.2k78%
Search → Pricing0.9k22%
Direct → Pricing1.6k64%
Direct → Docs0.9k36%
Pricing → Signup1.9k76%
Pricing → Left0.6k24%
Docs → Signup1.3k32%
Docs → Left2.8k68%
Traffic from channels to signups, node totals
NodeInOut
Search–4.1k
Direct–2.5k
Pricing2.5k2.5k
Docs4.1k4.1k
Signup3.2k–
Left3.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"Optional

    The value of the flow under the pointer and its share of the source node's outflow.

  • data-slot="chart-message"Optional

    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.

PropTypeDefaultDescription
nodes requiredreadonly FlowNode[]—
links requiredreadonly FlowLink[]—
variant"basic-sankey" | "gradient-sankey" | "vertical-sankey" | "alluvial" | "chord""basic-sankey"Figma variant. Default .
groupsreadonly { key: string; label?: string; color?: ChartColor }[]—Groups in legend order with colours (default: in node order, palette colours).
columnsreadonly string[]—: captions under the columns (stages), e.g. ["Q1", "Q2", "Q3"].
valueFormatterChartValueFormatter—
labelstring—
heightnumber—
state"ready" | "loading" | "empty" | "error"—
hiddenSeriesreadonly string[]—Group / node labels switched off in the legend: their flows fade.
activeIndexnumber | null—The active point (hovered or focused) as an index into , to control it yourself. shows none.
animateboolean—
animationKeystring | number—
defaultActiveIndexnumber | null—The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer.
descriptionstring—
onActiveIndexChange(index) => void—Called with the index when the pointer or the arrow keys move to another point, and with 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.
widthnumber—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("sankey-chart")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.