Skip to Content
kindui

Sankey Chart

Follow quantities as they split and merge through stages.

Use a Sankey chart to show how a total flows through stages, like energy from its sources through zones to its uses, where each ribbon's width is its share.

Hover a ribbon to see its value. Press a node in the legend to highlight its routes.

Installation

npx shadcn@latest add @kind-ui/sankey-chart

Composition

SankeyChart
├── SankeyChart.Nodes
│   ├── SankeyChart.Node
│   └── SankeyChart.NodeLabel
├── SankeyChart.Links
│   └── SankeyChart.Link
├── SankeyChart.Tooltip
├── SankeyChart.Legend
├── SankeyChart.Table
└── SankeyChart.Content

SankeyChart holds the flow data, the node config and the accessible name, and draws only the parts you add. SankeyChart.Nodes and SankeyChart.Links draw the bars and ribbons; leave one out and it isn't drawn. Give the chart a height, since it fills its container's width. SankeyChart.Content places your own HTML next to the legend.

Usage

Flow Data

data has nodes, each with a unique id and a name, and links, each with a unique id, a source and target node ID, and a value. The chart checks the data when it renders and throws on:

  • a node with no config entry, a link to a node that doesn't exist, or a cycle,
  • a negative or non-finite value,
  • a middle node whose inflow doesn't equal its outflow,
  • two links between the same nodes with the same value.

Model losses as links to their own end node, so every middle node balances. A link with a value of 0 isn't drawn, and a node with no drawn links leaves the plot. empty shows when no link has a positive value.

Node Colors

config gives every node ID a label and color, and the legend lists nodes in its order. A node takes its own color and a ribbon takes its source node's color. Pressing a legend item highlights the node and every route through it, and dims the rest.

Ribbons are opaque, so they hide each other where they cross. Return SankeyChart.Link from SankeyChart.Links' render, as above, with a lower strokeOpacity in pathProps to let crossings show through.

nodeWidth, nodePadding, linkCurvature and sort come from Recharts. Pass sort={false} to keep nodes in data order.

Labels and Gradients

Pass a render function to SankeyChart.Nodes to draw each node yourself. Return SankeyChart.Node with SankeyChart.NodeLabel beside it, and leave room for the labels with margin. showValues adds each node's total. Set material="gradient" on SankeyChart.Link to blend each ribbon from its source to its target color:

Each label shows its node's total. Ribbons blend from source to target.

A node's icon in config shows beside its label. position="inside" clips the label to the node instead; the tooltip still has the full name.

Set finish="clay" or "glow" on SankeyChart.Node or SankeyChart.Link for a surface finish; see Materials.

Accessibility

Ribbons and nodes aren't reachable from the keyboard on their own. Add SankeyChart.Table with a caption for a table of every link and its value. Pass it onInspect to add a button per row, and activeLinkId to mark the selected one, for a keyboard way to pick a flow. You can also give each SankeyChart.Link keyboard handlers and ARIA attributes through pathProps.

Motion

Pass animate to draw the ribbons in when the chart mounts, or animate={{ revealDurationMs: 900 }} to change the duration (450ms by default). Sankey charts don't animate by default. When the reader prefers reduced motion, the diagram appears without drawing in. See Motion.

Loading

Set loading while the data is on its way. The chart keeps its size and shows a placeholder diagram, which holds still when the reader prefers reduced motion. Screen readers hear loadingLabel ("Loading chart" by default):

<SankeyChart loading={isPending} loadingLabel="Loading energy flows" {...props}>

API Reference

SankeyChart

Prop

Type

Prop

Type

SankeyChart.Node

Prop

Type

SankeyChart.NodeLabel

Prop

Type

SankeyChart also takes every prop of Recharts' Sankey, like margin, nodeWidth and nodePadding, and its onClick, onMouseEnter and onMouseLeave receive the node or link with its id. SankeyChart.Tooltip takes every prop of Recharts' Tooltip, like formatter.