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 { AriaComponent, TooltipComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";

// Register required ECharts modules
echarts.use([SankeyChartType, AriaComponent, 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}
      ariaLabel="User traffic flow by destination"
      ariaDescription="Shows traffic flowing from users and devices to apps and tunnels."
    />
  );
}

Accessibility

Provide a localized ariaLabel and, when useful, ariaDescription so screen reader users know what the diagram represents. Register ECharts' AriaComponent to enable generated data summaries.

When onNodeClick or onLinkClick is provided, SankeyChart renders a keyboard-accessible fallback action list. Use keyboardActionsLabel, getNodeActionLabel, and getLinkActionLabel to localize those actions.

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)}
  ariaLabel="Interactive traffic flow"
  getNodeActionLabel={(node) => "Select " + node.name}
  getLinkActionLabel={(link, { sourceName, targetName }) =>
    "Select link from " + sourceName + " to " + targetName}
/>

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

Component "SankeyChart" not found in registry. Run pnpm build:ai-metadata to regenerate.

Kumo