Sankey Chart
Documentation Index
Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.
Visualize flow data as nodes and links, powered by Apache ECharts
Installation
Usage
The ECharts sankey chart is composible, sharing the Recharts twin's API shape. <EChartsSankeyChart> is the container, and every part hangs off it as a compound member — <EChartsSankeyChart.Node>, <EChartsSankeyChart.NodeLabel>, <EChartsSankeyChart.Link>, and <EChartsSankeyChart.Tooltip> — so a single import gives you the whole chart. Because nodes and links are intrinsic to the flow data, <Node> and <Link> always render and just configure the diagram; <NodeLabel> and <Tooltip> follow presence semantics — omit one and it does not render.
import { EChartsSankeyChart, type ChartConfig, type SankeyData } from "@/components/evilcharts/charts/echarts-sankey-chart";const data: SankeyData = {
nodes: [
{ name: "Visit" },
{ name: "Direct-Favourite" },
{ name: "Page-Click" },
{ name: "Detail-Favourite" },
{ name: "Lost" },
],
links: [
{ source: 0, target: 1, value: 3728 },
{ source: 0, target: 2, value: 354170 },
{ source: 2, target: 3, value: 62429 },
{ source: 2, target: 4, value: 291741 },
],
};
const chartConfig = {
Visit: {
label: "Visit",
colors: { light: ["#3b82f6"], dark: ["#60a5fa"] },
},
"Page-Click": {
label: "Page Click",
colors: { light: ["#f59e0b"], dark: ["#fbbf24"] },
},
// ... more node configs
} satisfies ChartConfig;
<EChartsSankeyChart data={data} config={chartConfig}>
<EChartsSankeyChart.Node isClickable>
<EChartsSankeyChart.NodeLabel position="outside" showValues />
</EChartsSankeyChart.Node>
<EChartsSankeyChart.Link variant="source" />
<EChartsSankeyChart.Tooltip />
</EChartsSankeyChart>The one real difference is under the hood: ECharts renders to a <canvas>, so these children never mount as DOM. The root reads their props and compiles them into the ECharts option — same JSX, same presence semantics, same behavior, but the children are declarative config, not live DOM nodes.
config is the same contract as every EvilCharts chart — each key maps a node name to a label and a per-theme colors array. See Chart Config for the full shape. Colors resolve from CSS variables at runtime, so dark mode just works.
Canvas rendering brings a few small departures from the Recharts twin: node
icons are not rendered, and verticalPadding on <Link> has no ECharts
equivalent (see the API notes). All link variants — gradient, solid,
source, and target — are supported.
Interactive Selection
Set isClickable on <Node> to make nodes selectable. The selected node and its
direct neighbors stay highlighted while the rest dim. Handle selection events with
the root's onSelectionChange callback:
<EChartsSankeyChart
data={data}
config={chartConfig}
onSelectionChange={(selection) => {
if (selection) {
console.log("Selected:", selection.dataKey, "Value:", selection.value);
} else {
console.log("Deselected");
}
}}
>
<EChartsSankeyChart.Node isClickable />
<EChartsSankeyChart.Link variant="source" />
<EChartsSankeyChart.Tooltip />
</EChartsSankeyChart>Loading State
Pass isLoading to <EChartsSankeyChart> to show an animated gray skeleton
while data loads.
Examples
Examples of the sankey chart in different configurations. Customize the <Link> variant, the root nodeWidth, nodePadding, and more.
Gradient Colors
Labeled Nodes
Display labels and values on nodes by composing a <NodeLabel /> inside <Node />.
Inside Labels
Use a larger nodeWidth (e.g., 80) on the root to accommodate the text.
Outside Labels
Link Variants
Set the link coloring strategy with the variant prop on <Link />.
Solid Links
Set <Link /> variant to "solid" for a single color across all links — clean and minimal.
Source-colored Links
Set <Link /> variant to "source" to color links by their source node, tracing where flows originate.
API Reference
A root container plus a small set of composible parts. Render the root, then compose the parts you need as children. On canvas each part is declarative config the root compiles, but the API closely mirrors the Recharts twin.
The root container. It owns the flow data, shared selection state, loading skeleton, and intro reveal. Everything visual is composed as children and compiled into the ECharts option.
Configures how the sankey nodes render. Compose a <NodeLabel /> inside it to show labels and values.
Declares labels for the <Node /> it is composed inside. With no position, no labels are shown.
Configures how the sankey links render.
The hover tooltip. Its presence enables it; omit it and none shows. Hovering a node shows its label and total flow; hovering a link shows the source → target flow and its value. Hidden automatically while loading.