Sankey Chart
Documentation Index
Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.
Our Sankey chart for visualizing flow data as connected nodes and links.
Overview
Use a Sankey chart to show how quantities flow between stages, groups, or systems. Keep node names concise and reduce crossing links so the dominant paths remain easy to follow.
Anatomy
SankeyChart owns the flow data, configuration, selection, and loading state. Node and Link configure the diagram, NodeLabel identifies each stage, and Tooltip exposes the values behind a connection.
Accessibility
Canvas charts need a nearby text summary or data table when the exact values are important. Use descriptive node labels and provide the major source-to-target flows in text so the diagram is not the only representation.
Installation
Usage
Our sankey chart is composable. <SankeyChart> is the container, and every part hangs off it as a compound member, <SankeyChart.Node>, <SankeyChart.NodeLabel>, <SankeyChart.Link>, and <SankeyChart.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 { SankeyChart, type ChartConfig, type SankeyData } from "honestui/charts";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;
<SankeyChart data={data} config={chartConfig}>
<SankeyChart.Node isClickable>
<SankeyChart.NodeLabel position="outside" showValues />
</SankeyChart.Node>
<SankeyChart.Link variant="source" />
<SankeyChart.Tooltip />
</SankeyChart>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 Honest UI 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 has a few implementation details to keep in mind: 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:
<SankeyChart
data={data}
config={chartConfig}
onSelectionChange={(selection) => {
if (selection) {
console.log("Selected:", selection.dataKey, "Value:", selection.value);
} else {
console.log("Deselected");
}
}}
>
<SankeyChart.Node isClickable />
<SankeyChart.Link variant="source" />
<SankeyChart.Tooltip />
</SankeyChart>Loading State
Pass isLoading to <SankeyChart> 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 composable parts. Render the root, then compose the parts you need as children. On canvas each part is declarative config the root compiles.
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.