Sankey API

Flows between nodes laid out in columns, with band thickness proportional to the flow value (built on d3-sankey) - see the Sankey demo.

Import

Web Component

import "@michi-vz/wc/sankey-chart";
// <michi-vz-sankey-chart> is now defined

Vanilla JS

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

const chart = mountSankeyChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years": snapshots one period at a time over the period tags in the data, with a headless controller (`chart.timeline()`) plus the built-in play button + scrubber. Values tween between periods unless `interpolate: false`. Off by default; wins over `progressiveDraw` when both are set.
progressiveDraw	boolean | ProgressiveDrawConfig	-	Opt-in reveal animation: wipes the marks in left to right on mount (a clip reveal; axes and titles stay put). `true` uses defaults (1200 ms, easeInOutCubic); a config tunes durationMs, easing, autoplay, and replayOnUpdate (`tipLabel` is LineChart-only and ignored here). Off by default; respects prefers-reduced-motion (renders fully drawn instantly) and `replay()` re-runs it.
nodes*	SankeyNodeItem[]	-	Flow nodes; each needs a unique id that links reference
links*	SankeyLinkItem[]	-	Directed flows between nodes (source -> target); band thickness is proportional to value
title	string	-	Optional chart title rendered above the plot
nodeWidth	number	18	Node rect width in px (default 18).
nodePadding	number	12	Vertical gap between nodes in a column in px (default 12).
nodeRadius	number	2	Corner radius of the node rects in px (default 2; 0 = square corners). Clamped to half the node's shorter side.
linkRadius	number	2	Corner radius (px) of the filled flow ribbons where they meet the nodes (default 2; 0 = sharp corners). Clamped to half the band's thickness.
linkColorMode	"source" | "target"	"source"	Colour links by their "source" (default) or "target" node.
linkOpacity	number	0.45	Link opacity in [0,1] (default 0.45).
showLabels	boolean	true	Draw node labels (default true).
isLoading	boolean	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
isNodata	boolean | ((dataSet: SankeyNodeItem[] | null | undefined) => boolean)	-	No-data override: boolean, or a predicate on nodes; default = empty nodes.
noDataLabel	string	-	Text for the vanilla default no-data overlay (ignored when suppressed).
suppressDefaultOverlay	boolean	-	A framework wrapper sets this to render its OWN loading/no-data node instead.
valueFormatter	(n: number) => string	-	Formats a numeric value for labels and tooltips
tooltipFormatter	(mark: SankeyNodeContext | SankeyLinkContext) => string	-	Returns custom tooltip HTML for a hovered datum/mark (sanitized before it is inserted)
onHighlightItem	(labels: string[]) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	800	Chart width in pixels
height	number	500	Chart height in pixels
margin	Margin	{ top: 36, right: 12, bottom: 12, left: 12 }	Inner margins (top/right/bottom/left, in px); default 8 (36 top with a title)
colors	string[]	-	Categorical palette for rings without an explicit colour or colorsMapping entry
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
highlightItems	string[]	-	Labels to emphasise (active styling); others keep their base opacity
disabledItems	string[]	-	Labels to hide entirely (ring + track removed; remaining rings keep their radii order)
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas / WebGPU layer; getContext() is identical either way
locale	string	-	BCP-47 locale used for number formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so arc colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate opacity/arc changes with CSS transitions (SVG renderer; default true)
onColorMappingGenerated	(mapping: Record<string, string>) => void	-	Called with the resolved label -> colour map after the chart assigns colours
onChartDataProcessed	(context: ChartContext) => void	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
onDataWarning	(warnings: DataWarning[]) => void	-	Called with any non-fatal data warnings (out-of-range values, duplicate labels, ...)

Data is two arrays

Unlike the other charts, a Sankey takes nodes ({ id, label?, color? }[]) and links ({ source, target, value }[]) instead of a single dataSet.

Events

The web component dispatches these bubbling CustomEvents (the engine exposes the same via the on* callbacks in the table above):

Event	Detail	Fires when
michi-vz:highlight	string[]	hover highlight changes (node id, or a link's source + target)
michi-vz:colormapping	Record<string, string>	a color mapping is generated
michi-vz:dataprocessed	ChartContext	data is (re)processed
michi-vz:datawarning	DataWarning[]	input warnings are detected (e.g. a link to an unknown node)

getContext()

mountSankeyChart(el, props).getContext() returns a renderer-agnostic SankeyChartContext: the nodes (id / label / color / value / column depth), the links (source / target / value / color), summary stats (node & link counts, column count, total flow, largest link, busiest node), a deterministic natural-language summary, and an a11y table listing the flows. See LLM context.

Source

Props are typed as SankeyChartProps in @michi-vz/core.