Flow Canvas
ProA canvas for a workflow: step cards joined by edges, a + on every edge to insert a step, zoom, a hand tool to pan and Tidy up for a clean top-to-bottom layout.
Playground
Drag a step, press Tab and Enter to open one, or Tidy up after moving things.
Installation
Flow Canvas comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
FlowCanvas,
FlowCanvasEdge,
FlowCanvasNode,
FlowCanvasProps,
FlowCanvasTool,
FlowNode,
} from "@wunderui/react"Status
FlowNode is the step card: an icon tile picked by the type, the title, a subtitle and a status badge. The status is in the badge text and in the step's name for screen readers, never only in the colour. Use FlowNode on its own for a list of steps.
Edges
An edge runs from an out port at the bottom of a step to an in port at the top of the next. A condition gets two out ports with a label each. Curves are the default; straight lines suit dense flows.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- 1data-slot="flow-canvas"
A clipped, 16 px rounded surface on bg-page with a dot grid that pans and zooms with the content. A named group (aria-roledescription "flow canvas") with keyboard help and a polite live region.
- 2data-slot="flow-node"
The step card, 240 × 64: an indigo icon tile picked by the type, the title, a subtitle and a status badge. In the canvas it is a focusable step; Enter opens it, Delete removes it through onNodeRemove, the arrow keys move it.
- 3data-slot="flow-canvas-port"
An 8 px dot on the card edge: in ports on the top, out ports on the bottom, spread evenly. Decorative; the edges carry the meaning.
- 4data-slot="flow-canvas-insert"Optional
A 24 px round button in the middle of every edge when onInsert is set, named after the two steps it sits between.
- 5data-slot="flow-canvas-edge-label"Optional
A small label under an out port, e.g. Yes and No on a condition.
- 6data-slot="flow-canvas-toolbar"Optional
Bottom-left: Select and Hand tools, zoom out, the zoom level (resets to 100 %), zoom in, fit to view and Tidy up. hideToolbar removes it.
- data-slot="flow-canvas-world"
- data-slot="flow-canvas-edges"
- data-slot="flow-canvas-node"Optional
- data-slot="flow-node-title"
Best practices
When to use
Use a Flow Canvas to build or show a workflow with branches: triggers, conditions and actions. For a run that already happened, in order, use a Run Timeline; for steps of a form, a Stepper.
- Do
Give every step a short title and a subtitle that starts with its role (When, If, Then), so the flow reads top to bottom.
- Do
Handle onNodeRemove with an Undo instead of a confirmation, and join the neighbours of the removed step.
- Do
Keep onNodesChange in your state so drags, keyboard moves and Tidy up survive a reload.
- Don’t
Don't use colour alone for a step's state; set status, which adds the badge text and the screen-reader name.
- Don’t
Don't put forms inside the step cards. Open the step (onNodeOpen) in a Sheet or a Floating Panel.
- Do
Use statusLabel for a status in your own words ("Needs Linear") and hue for the tile of a step; use onNodeSelect for a details panel instead of reading clicks off the DOM, and wrapTitles where step titles run long.
API reference
One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.
A clipped, 16 px rounded surface on bg-page with a dot grid that pans and zooms with the content. A named group (aria-roledescription "flow canvas") with keyboard help and a polite live region.
| Prop | Type | Default | Description |
|---|---|---|---|
| edges required | FlowCanvasEdge[] | — | |
| nodes required | FlowCanvasNode[] | — | |
| defaultTool | "select" | "hand" | "select" | |
| defaultZoom | number | 1 | |
| edgeShape | "curved" | "straight" | "curved" | Edges as curves (default) or straight lines. |
| hideToolbar | boolean | false | Hides the toolbar (tools, zoom, fit, Tidy up). |
| label | string | "Workflow" | Accessible name of the canvas. |
| layout | "auto" | — | places every node by the column layout and ignores /. |
| onInsert | (edgeId) => void | — | Shows a "+" button in the middle of every edge; called with the edge's id. |
| onNodeOpen | (id) => void | — | Enter or a double click on a node. |
| onNodeRemove | (id) => void | — | Delete or Backspace on a focused node. The caller removes it (and offers the undo). |
| onNodesChange | (nodes) => void | — | Called with the nodes and their new / after a drag, a keyboard move or "Tidy up". Without it the canvas keeps the positions itself. |
| onNodeSelect | (id) => void | — | A single click (without a drag) or keyboard focus selects a node; called with its id. A click on the empty canvas clears it with . |
| onToolChange | (tool) => void | — | |
| onZoomChange | (zoom) => void | — | |
| tool | "select" | "hand" | — | |
| wrapTitles | boolean | false | Lets long step titles wrap onto two lines (see ). |
| zoom | number | — |
The step card, 240 × 64: an indigo icon tile picked by the type, the title, a subtitle and a status badge. In the canvas it is a focusable step; Enter opens it, Delete removes it through onNodeRemove, the arrow keys move it.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | |
| hue | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "grey" | — | The tint of the icon tile; defaults to indigo (red on an step). |
| icon | ReactNode | — | |
| selected | boolean | false | |
| status | "warning" | "error" | "success" | "disabled" | "running" | "idle" | "idle" | |
| statusLabel | string | — | Replaces the status badge text (e.g. "Needs Linear"); the colour still comes from . |
| subtitle | ReactNode | — | |
| type | string | "action" | Picks the default icon (see ). |
| wrap | boolean | false | Lets the title wrap onto two lines (it clamps there, with the full text as a tooltip) instead of truncating on one. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("flow-canvas")The full library index for assistants is at /llms.txt.
Related components
- Done420 tok$0.01640ms
Input
status: overdue, age: 30+ daysOutput
14 invoices, $42,860 in total - Done3,420 tok$0.042.1s
Input
14 invoice idsOutput
14 contacts, all with an email address - Running2,310 tok
Input
template: invoice-overdue-30 - Pending
Input
to: 14 recipients - PendingLog the result
AI & Agents4 stylesProRun TimelineEvery step of a run in order, with duration, tokens and expandable input/output.