# Sankey flow

> Volumes flowing between stages as ribbons. Hover a stage to trace everything that passes through it.

Component · Pro · https://lodeui.com/components/sankey-flow

## When to use

- Showing how a volume splits and merges across stages: traffic to signups, budget to teams, energy to uses.
- Finding the biggest leaks between one step and the next.

## When not to use

- A single linear path with drop-off: use the funnel chart.
- Cycles (A → B → A): a Sankey needs flows that move forward.

## Installation

```bash
npx shadcn@latest add @lode/sankey-flow
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion

## Usage

```tsx title="example.tsx"
import { SankeyFlow } from "@/components/ui/sankey-flow";

const nodes = [
  { id: "search", label: "Search" },
  { id: "direct", label: "Direct" },
  { id: "trial", label: "Trial" },
  { id: "paid", label: "Paid" },
];
const links = [
  { source: "search", target: "trial", value: 4200 },
  { source: "direct", target: "trial", value: 1800 },
  { source: "trial", target: "paid", value: 1900 },
];

export function Flow() {
  return <SankeyFlow nodes={nodes} links={links} columns={["Source", "Trial", "Outcome"]} />;
}
```

## API reference

### SankeyFlow

Stages as bars, flows as ribbons sized by volume. Columns come from the links.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| nodes | `SankeyNode[]` | – | { id, label, color? }. Colour defaults to the chart palette. |
| links | `SankeyLink[]` | – | { source, target, value }. Links must point forwards; the column of each node is worked out from them. |
| columns | `string[]` | – | Titles above each column. |
| height | `number` | `360` | Height in px. Width fills the container. |
| format | `(n) => string` | – | Values beside nodes and in tooltips. |
| particles | `boolean` | `true` | Dots drifting along ribbons, more on bigger flows. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Move between stages |
| Focus a stage | Highlights everything flowing into and out of it |

## Accessibility

- Each stage is focusable with its value and share of the total.
- The chart has a text summary of the total and the number of stages.

## Motion

- Particles move along each ribbon in proportion to its volume.
- Particles are off for reduced motion and pause when the chart is off screen.

## Responsive behavior

- Width follows the container with a ResizeObserver; ribbons and labels re-lay out.

## Performance

- Particles are written to the DOM each frame without React re-renders; about 70 dots in total.

## Notes for AI

- Give every link a positive value; nodes are sized by the larger of what flows in and out.
- Use muted colours (var(--muted-foreground)) for drop-off nodes so the main path stands out.

## Related

- [Funnel chart](https://lodeui.com/components/funnel-chart) — Conversion funnel with overall and step-to-step rates.
- [Sunburst](https://lodeui.com/components/sunburst) — A hierarchy in rings: click a slice to make it the centre, and every arc swings around it.
- [Bar chart](https://lodeui.com/components/bar-chart) — Bars that grow in and morph between datasets, with a hover readout.