Sankey

Flow between stages, where band width is the quantity moving. Nodes are layered by longest path so every link runs forward, and a cycle is reported rather than drawn as something plausible.

src/components/ui/sankey.tsx

About

From the component's own source, where it was written.

Flow between stages, where the width of a band is the quantity moving.

**This is the chart for "where did it all go".** Traffic from source to landing page to conversion, a budget from department to project, energy from generation to loss — anything where a quantity splits and merges and the interesting part is the *proportion* taking each route. A funnel shows the same drop-off as a single column of shrinking bars; a Sankey shows where the loss went, which is usually the actual question.

**Nodes are placed in layers by longest path from a source, not by input order.** Using the order the caller happened to list them in produces backward-pointing links and a diagram that reads as a tangle. Layering by depth guarantees every link runs left to right.

**It requires a DAG and says so.** A cycle has no consistent layering — the depth of a node in a loop is undefined — so a cycle is detected and reported through onError rather than being drawn as something plausible but wrong.

Bands are cubic Béziers with horizontal control points, which is what keeps them readable where several cross: the eye follows a smooth curve through an intersection and loses a polyline.

Install

npx astralyx-ui add sankey

Usage

import { Sankey } from '@/components/ui/sankey'

<Sankey nodes={nodes} links={links} />

Composer

Change the props and the source below follows.

Sankey diagram
Organic → Landing: 4.2kOrganic → Docs: 2.6kPaid → Landing: 3.1kReferral → Docs: 900Referral → Landing: 600Landing → Sign-up: 2.4kLanding → Bounced: 5.5kDocs → Sign-up: 1.4kDocs → Bounced: 2.1kSign-up → Activated: 2.6kSign-up → Bounced: 1.2kOrganic: 6.8kPaid: 3.1kReferral: 1.5kLanding: 7.9kDocs: 3.5kSign-up: 3.8kActivated: 2.6kBounced: 8.8k
  • Organic6.8k
  • Paid3.1k
  • Referral1.5k
  • Landing7.9k
  • Docs3.5k
  • Sign-up3.8k
  • Activated2.6k
  • Bounced8.8k
Props
tsx
<Sankey
  nodes={nodes}
  links={links}
  nodeWidth={3}
/>

Examples

Acquisition to activation

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

Sankey

Extends Omit<ComponentProps<'figure'>, 'height' | 'onError'>.

PropTypeDefaultDescription
nodesSankeyNode[]required{ id, label, color? } and { source, target, value }.
linksSankeyLink[]required{ id, label, color? } and { source, target, value }.
heightnumber320—
nodeWidthnumber3Width of a node column, in the 100-wide coordinate space.
nodePaddingnumber2Vertical gap between nodes in the same layer.
valueFormat(value: number) => stringDEFAULT_FORMAT—
showValuesbooleantrue—
onError(error: Error) => void——
emptyLabelstring'No flows.'—
labelstring'Sankey diagram'—

Types

SankeyNode

Flow between stages, where the width of a band is the quantity moving.

FieldTypeDescription
idstring—
labelstring—
color?string—

Behaviour

TopicDetailDescription
vs Funnelwhere it wentA funnel shows the same drop-off as shrinking bars. A Sankey shows where the loss went, which is usually the actual question.
layeringlongest pathDerived, not taken from input order — laying nodes out in the order they were listed produces backward links and a tangle.
cyclesreportedDepth is undefined inside a loop, so a cycle raises onError instead of being drawn wrongly.
ribbonsfilled, not strokedThe plot is stretched to fill its box and a stroke under a non-uniform transform scales unevenly — the band width would change with the container’s aspect ratio, which is a lie about the quantity.