Sankey / Flow Diagram

Demo & usage

More examples

When to use

• Visualizing flow and proportion between stages: budgets, traffic, conversions, energy.
• You want link widths proportional to magnitude.
• The process loops — returns, refunds, recycled material. A backwards flow is drawn dashed and does not disturb the column order.
• For simple stage counts, a funnel (Other Types) is lighter.

Async states

• loading
• empty
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `nodes`, `loading` and `error`.
• Set `filtered` when a search or filter is active. It is the difference between "you have no orders" and "no orders match this filter" — telling a customer with 4,000 orders the first one reads as a bug.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Reproducible column layout: longest-path ranking, with `nodeOrder` choosing input order or heaviest-first within a column.
• Width-proportional links.
• Per-node and per-link colors.
• Backwards flows drawn dashed and excluded from ranking.

Best practices

• Do: Keep node labels short; long names crowd the columns.
• Do: Ensure inflow equals outflow per node so the diagram is honest.
• Do: Order the `nodes` array the way you want each column stacked. That array is the layout control: `nodeOrder="input"` follows it exactly, and the order of `links` no longer affects the picture at all.
• Don't: Send a negative value to mean a flow in the other direction. A ribbon has no direction but the one it is drawn in, so a negative magnitude is refused and reported rather than drawn as a thin positive flow. Reverse the source and target instead.
• Tip: Color links by source or category to make paths traceable.
• Tip: Read the note under the diagram during development. It names every flow that was refused — an unusable value, an unknown endpoint, a flow carrying nothing — which is usually a payload bug rather than a charting one.

Accessibility

• The SVG is a `role="group"` with a generated summary (override via `ariaLabel`) — `group`, not `img`, because the ribbons and nodes are tab stops.
• `sv-data-summary-table` publishes one row per flow, named "Source to Destination", with its value and its share of BOTH ends. Ribbon width is the value, and the two shares are what the picture makes obvious and a bare list of numbers does not: 60 out of a 600 source is a trickle, 60 into a 60 destination is everything that destination gets.
• A backwards flow is marked "(backwards)" in its row and in its accessible name, not only by the dash. The dash is the one part of the drawing a screen reader cannot report and a colour-blind reader can miss.
• The table lists what is actually on screen. A flow the chart refused is absent from it and named in the note instead, so the rows and the ribbons never disagree.
• Ribbons and nodes are keyboard-focusable `role="button"` elements with `aria-label`s; hover/focus shows the tooltip and Enter/Space emits `linkSelect`/`nodeSelect`. Labels carry meaning beyond color.