Sankey Chart

Sankey charts for flow data with nodes and links, plus gradient colors

Basic Chart

Installation

npx shadcn@latest add @evilcharts/recharts-sankey-chart

A compound component: <EvilSankeyChart /> is the container; <EvilSankeyChart.Node />, <EvilSankeyChart.Link />, and <EvilSankeyChart.Tooltip /> compose as children. Render only the parts you need.

import { EvilSankeyChart } from "@/components/evilcharts/charts/recharts-sankey-chart";
import { type ChartConfig } from "@/components/evilcharts/ui/recharts-chart";
import type { SankeyData } from "recharts";

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;
 
<EvilSankeyChart data={data} config={chartConfig}>
  <EvilSankeyChart.Node isClickable>
    <EvilSankeyChart.NodeLabel position="outside" showValues />
  </EvilSankeyChart.Node>
  <EvilSankeyChart.Link variant="source" />
  <EvilSankeyChart.Tooltip />
</EvilSankeyChart>

Interactive Selection

Set isClickable on <Node /> to select nodes on click. Handle events with the root's onSelectionChange callback:

<EvilSankeyChart
  data={data}
  config={chartConfig}
  onSelectionChange={(selection) => {
    if (selection) {
      console.log("Selected:", selection.dataKey, "Value:", selection.value);
    } else {
      console.log("Deselected");
    }
  }}
>
  <EvilSankeyChart.Node isClickable />
  <EvilSankeyChart.Link variant="source" />
  <EvilSankeyChart.Tooltip />
</EvilSankeyChart>

Loading State

isLoading='true'

Note

Pass isLoading to <EvilSankeyChart /> to show a placeholder animation of nodes and links while data loads.

Examples

Customize the <Link /> variant, the root nodeWidth, nodePadding, and more.

Gradient Colors

gradient colors

Labeled Nodes

Note

Display labels and values on nodes by composing a <NodeLabel /> inside <Node />.

Inside Labels

showNodeLabels='inside'

showNodeLabels='inside' - solid colors

Note

Use a larger nodeWidth (e.g., 80) on the root to fit the text. Add verticalPadding on <Link /> for space where links meet nodes.

Outside Labels

showNodeLabels='outside'

Link Variants

Note

The variant prop on <Link /> sets the link coloring strategy.

Solid Links

Note

Set <Link /> variant to "solid" for a single color across all links — clean and minimal.

Source-colored Links

Note

Set <Link /> variant to "source" to color links by their source node, tracing where flows originate.

API Reference

A root container plus a few composible parts. Render the root, then compose the parts you need.

EvilSankeyChart

The root container. Owns the flow data, layout config, shared context, and the loading skeleton.

Prop	Type	Default	Description
data*	SankeyData	–	Nodes and links for the diagram — nodes are entities, links are flows between them. `SankeyData` is `{ nodes: SankeyNode[]; links: SankeyLink[] }`, where `SankeyNode = { name: string; icon?: ReactNode }` and `SankeyLink = { source: number; target: number; value: number }`.
config*	ChartConfig	–	Defines the chart's nodes. Each key matches a node name from your data and sets its colors.
children*	ReactNode	–	The composed parts — `<Node />`, `<Link />`, and `<Tooltip />`.
className	string	–	Extra CSS classes for the chart container.
nodeWidth	number	10	The width of each node in pixels.
nodePadding	number	10	The vertical padding between nodes in pixels.
linkCurvature	number	0.5	The curvature of links between nodes. Value between 0 (straight) and 1 (maximum curve).
iterations	number	32	Iterations for the Sankey layout algorithm. Higher values improve the layout but take more time.
sort	boolean	true	Whether to sort nodes automatically for optimal layout.
align	left\|justify	"justify"	Horizontal alignment for nodes. `"left"` aligns left; `"justify"` spreads them across the width.
verticalAlign	justify\|top	"justify"	Vertical alignment for nodes. `"top"` aligns to top; `"justify"` distributes vertically.
backgroundVariant	BackgroundVariant	–	Background pattern variant to display behind the chart.
defaultSelectedNode	string \| null	null	The node name selected on first render.
onSelectionChange	(selection: { dataKey: string; value: number } \| null) => void	–	Called when a node is selected or deselected. Receives an object with `dataKey` (node name) and `value` (calculated from links), or `null` when deselected. Fires on node click when `<Node />` has `isClickable` set.
isLoading	boolean	false	Shows a loading placeholder animation when data is being fetched.
sankeyProps	Omit<SankeyProps, "data">	–	Extra props for the underlying Recharts Sankey component. See the Recharts Sankey documentation for available props.

Node

Configures how nodes render. Compose a <NodeLabel /> inside to show labels and values.

Prop	Type	Default	Description
radius	number	0	The corner radius of node rectangles in pixels. Set to 0 for square nodes.
isClickable	boolean	false	Lets nodes be clicked to select or deselect them. Selected nodes highlight while the rest, and their links, dim.
children	ReactNode	–	Optional `<NodeLabel />` composition.

NodeLabel

Declares labels for the <Node /> it is composed inside.

Prop	Type	Default	Description
position	inside\|outside	–	Label position. `"inside"` shows labels inside nodes; `"outside"` shows them beside nodes. Without `<NodeLabel />`, no labels render.
showValues	boolean	false	Whether to display the total flow value alongside each node label.
valueFormatter	(value: number) => string	(value) => value.toLocaleString()	Function to format node values when `showValues` is enabled.

Link

Configures how links render.

Prop	Type	Default	Description
variant	gradient\|solid\|source\|target	"gradient"	Coloring strategy for links. `"gradient"` fades source to target; `"solid"` uses one color; `"source"` uses the source node color; `"target"` uses the target node color.
verticalPadding	number	0	Vertical padding where links connect to nodes in pixels. Useful when using node labels.

Tooltip

The hover tooltip. Hidden automatically while the chart is loading.

Prop	Type	Default	Description
variant	default\|frosted-glass	"default"	Controls the visual style of the tooltip.
roundness	sm\|md\|lg\|xl	"lg"	Controls the border-radius of the tooltip.
defaultIndex	number	–	When set, shows the tooltip by default at this data point index.