FlowEditor

Organism
A node-graph editor: cards placed freely on a pannable, zoomable canvas, joined by directed edges. Use it to let people shape a process, such as a delivery workflow whose edges carry conditions. The application owns the graph; FlowEditor draws the nodes and edges it is given and reports what the user asked for (onMoveNode, onConnect, onAddNode, onDelete, onSelectionChange).

Playground

Every control sets a real prop of FlowEditorProps. The JSX below updates as you go.
Props
label
string
readOnly
boolean
freePlacement
boolean
JSX · FlowEditorProps
<Stateful initial={{
nodes: [
{ id: "product", label: "Product", description: "Requirements", x: 0, y: 48 },
{ id: "design", label: "Design", description: "Mockups", x: 240, y: 48 },
{ id: "build", label: "Engineering", x: 480, y: 48 },
],
edges: [
{ id: "e1", from: "product", to: "design", label: "Ready" },
{ id: "e2", from: "design", to: "build", label: "Ready" },
{ id: "e3", from: "build", to: "design", label: "Contract changed", rework: true },
],
}}>
{(graph, setGraph) => (
<FlowEditor label="Delivery workflow" nodes={graph.nodes} edges={graph.edges}
palette={[{ id: "review", label: "Review" }]}
onMoveNode={(id, point) => setGraph({ ...graph, nodes: graph.nodes.map((n) => n.id === id ? { ...n, ...point } : n) })}
onConnect={(from, to) => setGraph({ ...graph, edges: [...graph.edges, { id: `${from}-${to}`, from, to, label: "Ready" }] })}
onAddNode={(kind, point) => setGraph({ ...graph, nodes: [...graph.nodes, { id: `${kind}-${graph.nodes.length}`, label: "Review", ...point }] })}
onDelete={(selection) => setGraph(selection.kind === "node"
? { nodes: graph.nodes.filter((n) => n.id !== selection.id), edges: graph.edges.filter((e) => e.from !== selection.id && e.to !== selection.id) }
: { ...graph, edges: graph.edges.filter((e) => e.id !== selection.id) })} />
)}
</Stateful>

Variants

2 examples from src/organisms/flow-editor/flow-editor.md, each rendered live from its own JSX.
Read only
Pass readOnly to show a graph without editing it: the toolbar, the ports and card drags are gone, while panning, zooming and selection stay, so a selected card or edge can drive a detail panel beside the editor.
<FlowEditor readOnly label="Published workflow, version 2"
nodes={[
{ id: "intake", label: "Intake", x: 0, y: 0 },
{ id: "product", label: "Product", x: 240, y: 0 },
{ id: "done", label: "Done", x: 480, y: 0 },
]}
edges={[
{ id: "a", from: "intake", to: "product", label: "Triage chose Product" },
{ id: "b", from: "product", to: "done", label: "Ready" },
]} />
Free placement
Cards snap to a 24-point grid by default. Pass freePlacement to keep them exactly where they are dropped.
<FlowEditor freePlacement label="Sketch"
nodes={[{ id: "a", label: "Start", x: 13, y: 7 }, { id: "b", label: "Finish", x: 251, y: 61 }]}
edges={[{ id: "ab", from: "a", to: "b" }]} />

Anatomy

1
Toolbar
2
Canvas
3
Node
4
Port
5
Edge
6
Edge label
Dimmed parts appear only in some states or variants.

Props

14 props on FlowEditorProps, grouped as they are declared in source. Required props are marked *.
Prop
Type
Default
Description
Props
14 props
label *
string
–
Accessible name of the canvas, such as "Workflow version 3".
nodes *
FlowNode[]
–
The cards, controlled.
edges *
FlowEdge[]
–
The connections, controlled.
palette
FlowPaletteItem[]
–
Kinds of node the user can add; omit for no palette.
selected
FlowSelection | null
–
Controlled selection; null selects nothing. Omit for uncontrolled use.
defaultSelected
FlowSelection | null
–
Initial selection for uncontrolled use.
onSelectionChange
(selection: FlowSelection | null) => void
–
Fired when the selection changes, in both modes.
onMoveNode
(id: string, point: FlowPoint) => void
–
A card was moved to a new top-left corner (snapped unless freePlacement).
onConnect
(from: string, to: string) => void
–
The user asked for an edge between two cards.
onAddNode
(paletteId: string, point: FlowPoint) => void
–
The user asked to add a node of a palette kind with its top-left corner at point.
onDelete
(selection: FlowSelection) => void
–
The user asked to delete the selected node or edge.
readOnly
boolean
false
Show the graph without editing: no toolbar edits, drags or ports; pan, zoom and selection stay.
freePlacement
boolean
false
Place cards exactly where they are dropped instead of on the grid.
testID
string
–
E2E hook forwarded to the root element.

Accessibility and keyboard

Keyboard
Tab
Shift+Tab
Moves between the toolbar, the canvas and each card
Arrow keys
Move the focused card one grid step
Delete
Backspace
Removes the selected card or edge
+
-
Zooms the canvas in or out
0
Fits the whole graph in view
Semantics
Roles
button
States
selected
ARIA on web
aria-hidden
aria-label
aria-pressed
From the docs
Every pointer action has a keyboard and screen-reader path. Each card is a focusable button named by its title, description, agent line, attention reason and incoming and outgoing connections. Each connection names its source and destination, its label when provided, and whether it is a rework edge; isolated cards announce no connections in either direction. These names follow graph updates and remain available in readOnly mode. Edges with a missing source or destination are omitted, just as they are from the drawing.
Cards announce selection (pressed state on the web); Enter or Space selects a focused card. In editable mode, the arrow keys move a focused card one grid step and Delete removes it, and VoiceOver and TalkBack offer the same as named actions (move left, right, up and down, delete). Read-only cards retain selection without editing actions. The toolbar's From and To selects with Connect join two cards without dragging a port; when the two are joined already the button reads Disconnect and removes that edge, the keyboard path to an edge. Each palette entry adds its node in view when pressed. The canvas itself takes focus: plus and minus zoom and 0 fits the graph. Edges are selected by pressing them or their label; Delete removes the selection in editable mode.

Platform skins

The playground's props on each platform: same tree, native shapes, type and touch sizes.
Web
control 10 · field 10 · card 16 · Instrument Sans
iOS
capsule controls · field 8 · card 12 · SF Pro · 44 pt
Android
Material 3 stadium · field 4 · card 12 · Roboto · 48 dp

Usage

<Stateful initial={{
nodes: [
{ id: "product", label: "Product", description: "Requirements", x: 0, y: 48 },
{ id: "design", label: "Design", description: "Mockups", x: 240, y: 48 },
{ id: "build", label: "Engineering", x: 480, y: 48 },
],
edges: [
{ id: "e1", from: "product", to: "design", label: "Ready" },
{ id: "e2", from: "design", to: "build", label: "Ready" },
{ id: "e3", from: "build", to: "design", label: "Contract changed", rework: true },
],
}}>
{(graph, setGraph) => (
<FlowEditor label="Delivery workflow" nodes={graph.nodes} edges={graph.edges}
palette={[{ id: "review", label: "Review" }]}
onMoveNode={(id, point) => setGraph({ ...graph, nodes: graph.nodes.map((n) => n.id === id ? { ...n, ...point } : n) })}
onConnect={(from, to) => setGraph({ ...graph, edges: [...graph.edges, { id: `${from}-${to}`, from, to, label: "Ready" }] })}
onAddNode={(kind, point) => setGraph({ ...graph, nodes: [...graph.nodes, { id: `${kind}-${graph.nodes.length}`, label: "Review", ...point }] })}
onDelete={(selection) => setGraph(selection.kind === "node"
? { nodes: graph.nodes.filter((n) => n.id !== selection.id), edges: graph.edges.filter((e) => e.from !== selection.id && e.to !== selection.id) }
: { ...graph, edges: graph.edges.filter((e) => e.id !== selection.id) })} />
)}
</Stateful>
Drag a card to move it (it snaps to the grid on release), drag from a card's right-hand port onto another card to connect them, and drag a palette entry onto the canvas to add a node. Drag the background to pan; the wheel, a pinch or the toolbar zoom buttons zoom, and Fit shows the whole graph. A rework edge, one that returns work upstream, is drawn dashed.

Who acts on a card

A node's optional agent is a compact third line naming who acts on the card, such as a role and its skill count. The card keeps its size: its padding tightens when the line is shown. A node's optional attention is the reason the card needs attention: it draws a warning mark in the card's top-right corner, and the card's accessible name ends with "needs attention:" and the reason. The mark is not interactive; the application shows the detail, for example in an inspector.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.
background
border
card
field-border
foreground
input
muted-foreground
primary
ring
subtle-foreground
surface-sunken
warning

Related components