# Flow Canvas

A workflow canvas: step cards with ports, edges with a + to insert a step, zoom, a hand tool and Tidy up for a top-to-bottom layout.

- Category: Data & Tables
- Page: https://wunderui.com/components/flow-canvas
- Tier: Core and Pro

## Install

Flow Canvas ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { FlowCanvas, FlowCanvasEdge, FlowCanvasNode, FlowCanvasProps, FlowCanvasTool, FlowNode } from "@wunderui/react"
```

## Anatomy

- `FlowCanvas`: 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.
- `FlowNode`: 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.
- `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.
- `Insert button`: A 24 px round button in the middle of every edge when onInsert is set, named after the two steps it sits between.
- `Edge label`: A small label under an out port, e.g. Yes and No on a condition.
- `Toolbar`: 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.
- `World`
- `Edges`
- `Node`
- `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.
- Handle onNodeRemove with an Undo instead of a confirmation, and join the neighbours of the removed step.
- Keep onNodesChange in your state so drags, keyboard moves and Tidy up survive a reload.
- 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.

### 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 put forms inside the step cards. Open the step (onNodeOpen) in a Sheet or a Floating Panel.

## API reference

### FlowCanvas

| Prop | Type | Default | Description |
|---|---|---|---|
| edges* | FlowCanvasEdge[] |  |  |
| nodes* | 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" |  | `"auto"` places every node by the column layout and ignores `x`/`y`. |
| onInsert | (edgeId: string) => void |  | Shows a "+" button in the middle of every edge; called with the edge's id. |
| onNodeOpen | (id: string) => void |  | Enter or a double click on a node. |
| onNodeRemove | (id: string) => void |  | Delete or Backspace on a focused node. The caller removes it (and offers the undo). |
| onNodesChange | (nodes: FlowCanvasNode[]) => void |  | Called with the nodes and their new `x`/`y` after a drag, a keyboard move or "Tidy up". Without it the canvas keeps the positions itself. |
| onNodeSelect | (id: string \| null) => 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 `null`. |
| onToolChange | (tool: FlowCanvasTool) => void |  |  |
| onZoomChange | (zoom: number) => void |  |  |
| tool | "select" \| "hand" |  |  |
| wrapTitles | boolean | false | Lets long step titles wrap onto two lines (see `FlowNode` `wrap`). |
| zoom | number |  |  |

Also accepts React.HTMLAttributes attributes.

### FlowNode

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  |  |
| hue | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "grey" |  | The tint of the icon tile; defaults to indigo (red on an `error` step). |
| icon | React.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 `status`. |
| subtitle | React.ReactNode |  |  |
| type | string | "action" | Picks the default icon (see `FlowCanvasNode.type`). |
| 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. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Status: what a step shows during a run

### Edges: curves or straight lines

## In context

### Workflow builder: insert, remove, undo

The + on an edge adds a step between its ends; Delete on a focused step removes it and joins its neighbours, with Undo under the canvas. layout="auto" keeps the columns tidy as the flow changes.

### Step options: status label, tile hue, two-line title

`statusLabel` replaces the badge text ("Needs Linear") while the colour still comes from `status`; `hue` tints the icon tile; `wrap` (on the canvas: `wrapTitles`) lets a long title take two lines. On the canvas, `onNodeSelect` reports a single click or focus, `null` for a click on the empty canvas.

## For AI agents

`get_component("flow-canvas")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
