Sankey

Flow

"Where does it all go?" A Sankey diagram traces flow through a system: nodes are laid out in columns, and the thickness of each band is the flow value. It is the right picture for trade between exporters and markets, budget from sources to uses, traffic from referrers to pages - anywhere a quantity splits and recombines on its way across.

Example

canvas · responsive

Go deeper: Insights guide·DevTools guide

Layout is computed with d3-sankey: nodes are assigned to columns from the graph topology, packed vertically, and links drawn as smooth horizontal bands. Hover a node or a flow for its figures.

When to reach for it

• Flows with structure. Trade between exporters and markets, budget from sources to uses, users through a funnel: where quantities come from, where they go, what splits and recombines.
• Finding the dominant path and the leaks. Band thickness is the value, so the thick routes and the thin losses read instantly - the audit view of any system.
• Only one stage? If nothing flows through, a Comparable bar ranks sources more cleanly than a two-column Sankey.

Heavy data on WebGPU Experimental

This chart's opt-in renderer="webgpu" paints its marks on the GPU while axes/labels/tooltips stay on SVG; capability-gated with automatic canvas fallback.

⚗️ Experimental - not yet stable. WebGPU rendering is an opt-in preview. It needs a WebGPU-capable browser (Chrome / Edge, or Safari 26+); everywhere else it falls back to canvas automatically. Axes, labels and tooltips stay on the SVG layer - only the data marks are painted on the GPU.

Heavy-data demo · ~150 links… detecting

Play through the years

Tag every link with a date and flip on timeline: a year's snapshot is the links sharing that date - nodes are shared across years, only the flows come and go - and band thickness tweens between years. Off by default - nothing changes until a chart opts in. This is interactive year-by-year stepping, not the one-shot entrance further down.

Press the play button under the chart: it steps through the years, one snapshot at a time. Drag the scrubber to jump to any year.

React

const ref = useRef<SankeyChartHandle>(null);

<SankeyChart ref={ref} {...props} timeline={{ speedMs: 1000, loop: true }} />;
// ref.current?.timeline() -> play() / pause() / seek(year) / stepForward()

Vue

<SankeyChart :options="{ ...props, timeline: { speedMs: 1000, loop: true } }" />

Svelte

<div use:sankeyChart={{ ...props, timeline: { speedMs: 1000, loop: true } }}></div>

Angular

applySankeyChartProps(this.c.nativeElement, { ...props, timeline: { speedMs: 1000, loop: true } });

Web component

<michi-vz-sankey-chart id="c"></michi-vz-sankey-chart>
<script>
  const el = document.getElementById("c");
  el.timeline = { speedMs: 1000, loop: true };
  // el.getTimeline() -> play() / pause() / seek(year)
</script>

• speedMs sets the pace, loop wraps around, autoplay: true starts on mount, showControl: false hides the built-in bar.
• Values glide between periods by default (interpolate); tune the motion with tweenMs and easing, or set interpolate: false for hard cuts. Reduced motion always gets the hard cut.
• The headless controller is always available: chart.timeline() exposes play() / pause() / toggle() / seek(period) / stepForward() / stepBack(), plus onStep and formatPeriod in the config for custom UI.
• Links without a date stay visible in every period.
• timeline wins over progressiveDraw when both are set - the reveal animation further down stays off while the timeline is in control.

Reveal animation

The chart wipes in from left to right on mount, revealing its marks in sequence before settling into place. Off by default - a chart opts in with the progressiveDraw prop.

The marks wipe in from left to right; axes and titles stay put. With reduced motion enabled, the chart renders fully drawn instantly.

progressiveDraw: true enables the defaults (1200 ms, easeInOutCubic). A config object tunes it:

React

const ref = useRef<SankeyChartHandle>(null);

<SankeyChart
  ref={ref}
  {...props}
  progressiveDraw={{ durationMs: 2000 }}
/>;
// ref.current?.replay() re-runs the reveal on demand

Vue

<SankeyChart :options="{ ...props, progressiveDraw: { durationMs: 2000 } }" />

Svelte

<div use:sankeyChart={{ ...props, progressiveDraw: { durationMs: 2000 } }}></div>

Angular

applySankeyChartProps(this.c.nativeElement, {
  ...props,
  progressiveDraw: { durationMs: 2000 },
});

Web component

<michi-vz-sankey-chart id="c"></michi-vz-sankey-chart>
<script>
  const el = document.getElementById("c");
  el.progressiveDraw = { durationMs: 2000 };
  // el.replay() re-runs the reveal
</script>

• durationMs and easing ("linear", "easeOutQuad", "easeInOutCubic", or a custom (t) => t function) shape the sweep.
• autoplay: false renders the chart fully drawn; call replay() (React ref handle, web-component method, or the core instance) to run the reveal on demand. replayOnUpdate: true re-runs it on every data change.
• Respects prefers-reduced-motion: the chart renders fully drawn instantly.
• Reveal animation is a one-shot entrance; play through the years above steps through data year by year instead.

Usage

React

import { SankeyChart } from "@michi-vz/react";

export default () => <SankeyChart {...props} />; // props = the chart options

Vue

<script setup>
import { SankeyChart } from "@michi-vz/vue";
</script>

<template>
  <SankeyChart :options="props" />
</template>

Svelte

<script>
  import { sankeyChart } from "@michi-vz/svelte";
</script>

<div use:sankeyChart={props}></div>

Angular

// main.ts - register the elements once
import "@michi-vz/angular";
import { applySankeyChartProps } from "@michi-vz/angular";

// component (uses CUSTOM_ELEMENTS_SCHEMA)
// template: <michi-vz-sankey-chart #c></michi-vz-sankey-chart>
applySankeyChartProps(this.c.nativeElement, props);

Web component

<script type="module" src="https://cdn.jsdelivr.net/npm/@michi-vz/wc/dist/michi-vz-wc.bundle.js"></script>

<michi-vz-sankey-chart id="c"></michi-vz-sankey-chart>
<script>
  Object.assign(document.getElementById("c"), props); // nodes, links, …
</script>

Vanilla JS

import { mountSankeyChart } from "@michi-vz/core";

const chart = mountSankeyChart(el, props);
chart.update(next);
chart.getContext(); // renderer-agnostic, LLM-ready
chart.destroy();

Data shape

Unlike the other charts, a Sankey takes two arrays: nodes (each with a unique id, an optional label and color) and links (source → target by id, with a value).

const props = {
  linkColorMode: "source", // colour links by their source (or "target")
  nodes: [
    { id: "France" }, { id: "Germany" },
    { id: "EU" }, { id: "Asia" },
  ],
  links: [
    { source: "France", target: "EU", value: 40 },
    { source: "France", target: "Asia", value: 22 },
    { source: "Germany", target: "EU", value: 55 },
    { source: "Germany", target: "Asia", value: 35 },
  ],
};

A link to an unknown node id (or a node in disabledItems) is dropped with a datawarning; disabling a node drops its links too.

Layout knobs

nodeWidth sets the node rect width, nodePadding the vertical gap between nodes in a column, and linkOpacity how translucent the bands are. linkColorMode colours each band by its source (default) or target node. The a11y mirror and getContext() expose the links as a readable "Source → Target: value" table.

Rounded nodes. nodeRadius (px, default 2) rounds the node rect corners - bump it up for the pill look, or set 0 for square corners. It's clamped to half the node's shorter side, so it never deforms a thin node.

Rounded flows. The flows are drawn as filled ribbons; linkRadius (px, default 2) rounds their corners where they meet the nodes, for a softer connection (clamped to half the band's thickness; 0 = sharp). linkColorMode colours each flow by its source or target node, at linkOpacity:

const props = { nodeRadius: 4, linkRadius: 4, /* …nodes, links */ };

API

Props are typed as SankeyChartProps in @michi-vz/core. Shared across all charts: width, height, margin, colors / colorsMapping, renderer ("svg", "canvas", or experimental "webgpu"), highlightItems, disabledItems, and the on* callbacks. onChartDataProcessed / getContext() return the renderer-agnostic ChartContext. Full reference: Sankey API.