Sankey Chart

<SankeyChart nodes={nodes} links={links} height={300} />

Installation

SankeyChart requires echarts as a peer dependency.

npm install echarts

Barrel

import { SankeyChart } from "@cloudflare/kumo";

Granular

import { SankeyChart } from "@cloudflare/kumo/components/chart";

Usage

import { SankeyChart, ChartPalette } from "@cloudflare/kumo";
import * as echarts from "echarts/core";
import { SankeyChart as SankeyChartType } from "echarts/charts";
import { TooltipComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";

// Register required ECharts modules
echarts.use([SankeyChartType, TooltipComponent, CanvasRenderer]);

const nodes = [
  { name: "Users", value: 103600, color: ChartPalette.categorical(0) },
  { name: "Devices", value: 50800, color: ChartPalette.categorical(1) },
  { name: "Apps", value: 122600, color: ChartPalette.categorical(2) },
  { name: "Tunnels", value: 31800, color: ChartPalette.categorical(3) },
];

const links = [
  { source: 0, target: 2, value: 80000 },
  { source: 0, target: 3, value: 23600 },
  { source: 1, target: 2, value: 42600 },
  { source: 1, target: 3, value: 8200 },
];

export default function Example() {
  return <SankeyChart echarts={echarts} nodes={nodes} links={links} height={300} />;
}

Examples

Basic Sankey

A simple Sankey diagram showing flow between source and target nodes.

<SankeyChart nodes={nodes} links={links} height={300} />

Multi-Level Flow

Sankey diagrams can show multiple levels of flow through intermediate nodes.

<SankeyChart nodes={nodes} links={links} height={350} nodeWidth={20} nodePadding={15} />

Full-Width Layout

Use left and right to control horizontal padding of the Sankey layout within its container. Set both to 0 to eliminate the default 5% padding and fill the full width.

<SankeyChart
  nodes={nodes}
  links={links}
  height={350}
  left={0}
  right={0}
/>

Rich Tooltips

Use tooltipFormatter for full control over tooltip content.

import { SankeyChart, type SankeyTooltipParams } from "@cloudflare/kumo";

const customTooltip = (params: SankeyTooltipParams) => {
  if (params.type === "node" && params.node) {
    return "<strong>" + params.name + "</strong>";
  }
  if (params.type === "link" && params.link) {
    return params.link.source + " → " + params.link.target;
  }
  return "";
};

<SankeyChart 
  nodes={nodes} 
  links={links} 
  tooltipFormatter={customTooltip} 
/>

Interactive

Use onNodeClick and onLinkClick to handle interactions.

<SankeyChart 
  nodes={nodes} 
  links={links} 
  onNodeClick={(node) => console.log(node)}
  onLinkClick={(link) => console.log(link)}
/>

Drill-Down Filtering

Click a source node to filter the chart and show only its connections. Click again or use the reset button to restore the full view.

Click a node to filter

const [selectedSource, setSelectedSource] = useState<string | null>(null);

const handleNodeClick = (node: { name: string }) => {
  if (sourceNames.includes(node.name)) {
    setSelectedSource(prev => prev === node.name ? null : node.name);
  }
};

<SankeyChart
  nodes={filteredNodes}
  links={filteredLinks}
  onNodeClick={handleNodeClick}
/>

Inline Label Layout

Use nodeLabelLayout="inline" to display node values and names on a single line. This prevents label overlap on small nodes where the default stacked layout would cause text to collide.

<SankeyChart
  echarts={echarts}
  nodes={nodes}
  links={links}
  height={300}
  nodeLabelLayout="inline"
/>

API Reference

Prop	Type	Default	Description
echarts*	`typeof echarts`	-	The ECharts core instance imported by the consumer. Passed in rather than imported directly so the consumer controls which ECharts modules are bundled (tree-shaking).
nodes*	`SankeyNodeData[]`	-	Array of nodes in the Sankey diagram
links*	`SankeyLinkData[]`	-	Array of links connecting nodes by index
height	`number`	-	Height of the chart in pixels
showNodeValues	`boolean`	-	Show node values above labels (default: true if any node has a value)
nodeLabelLayout	`"stacked" \| "inline"`	-	Layout for node labels when showNodeValues is true. - 'stacked': value on top, name below (default) - 'inline': "value name" on a single line (better for small nodes)
formatValue	`(value: number) => string`	-	Format function for node values (default: toLocaleString)
tooltipFormatter	`(params: SankeyTooltipParams) => string`	-	Custom tooltip formatter. Return HTML string or empty string to hide tooltip.
nodeWidth	`number`	-	-
nodePadding	`number`	-	-
showTooltip	`boolean`	-	-
defaultNodeColor	`string`	-	-
left	`number \| string`	-	Left padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'.
right	`number \| string`	-	Right padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'.
linkColor	`"gradient" \| "gray"`	-	Link fill style: 'gradient' blends source to target colors, 'gray' uses flat gray
linkOpacity	`number`	-	-
className	`string`	-	-
isDarkMode	`boolean`	-	-

Kumo