Workflow Canvas

Pro

A node editor for automations and agent workflows. Steps are cards on a dotted canvas, joined by curves you draw from port to port. Pan, zoom, drag, connect and run, by pointer or by keyboard.

TriggerLive
New ticket

When a ticket arrives

EmailChatWeb form
Agent2 tools
Classify intent

Sets topic and urgency

Knowledge baseOrder lookup
ToolGET
Look up customer

Plan, region and orders

/v1/customers?email={from}
Logic2 paths
Is it urgent?

urgency is High

Action
Page on-call

Pings the support rota

Action
Draft a reply

For an agent to review

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add workflow-canvas

Usage#

The canvas is composed, not fed a config. Each WorkflowNode is a card you fill with the parts you need, and each WorkflowEdge names the two nodes it joins. Positions live in the nodes, the list of edges lives in your state: onConnect tells you about a new connection and you decide whether to add it.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Anatomy#

import {  WorkflowCanvas,  WorkflowControls,  WorkflowEdge,  WorkflowNode,  WorkflowNodeBody,  WorkflowNodeContent,  WorkflowNodeDescription,  WorkflowNodeHeader,  WorkflowNodeIcon,  WorkflowNodeLabel,  WorkflowNodeTitle,  WorkflowPort,} from "@/components/ui/workflow-canvas"<WorkflowCanvas>  <WorkflowEdge />  <WorkflowNode>    <WorkflowNodeLabel />    <WorkflowNodeBody>      <WorkflowNodeHeader>        <WorkflowNodeIcon />        <WorkflowNodeTitle />      </WorkflowNodeHeader>      <WorkflowNodeDescription />      <WorkflowNodeContent />    </WorkflowNodeBody>    <WorkflowPort type="in" />    <WorkflowPort type="out" />  </WorkflowNode>  <WorkflowControls /></WorkflowCanvas>

Node kinds#

Five kinds cover most automations: a trigger starts the run, an agent reasons, a tool calls out, logic decides and an action does the work. A node is a tinted frame holding a white sheet, the same inset look as Tool and Code Snippet. The frame carries the kind, its dot and a category chip; the sheet carries the step. The kind only colours that dot, so a long workflow reads calmly. Every part below the root is optional: these nodes carry a title and nothing else.

Trigger
Every Monday 9:00
Agent
Summarise last week
Tool
Query the orders table
Logic
Wait for approval
Action
Email the team

Branches#

A node can have several outputs. Give each WorkflowPort an id and a position along the bottom edge, then point an edge at it with from="plan:pro". An edge's label sits at the middle of its curve.

Logic3 paths
Which plan?

Routes by the account's plan

Action
Send the nurture series
Action
Invite to a workspace
Action
Notify the account owner

Steps panel#

WorkflowPalette is a floating panel of the steps you can add, docked to the left of the canvas. It has a search field, groups and rows with the same anatomy as a menu. Click a row and onSelect fires, so you can add the step in the middle of the view with useWorkflowCanvas().viewportCenter(). Or drag the row onto the canvas: onDropStep on the canvas receives its value and the drop point. Fit and the controls make room for it. On a canvas narrower than 60rem, like this column, it folds away behind a Steps button in the controls, and it steps aside while the settings panel is open. Try it in the first example.

Settings panel#

Click a step and its settings open in a WorkflowInspector, a panel docked to the right of the canvas, the mirror of the steps panel. It shows while a node is selected (or when you pass open), closes with its close button, Escape or a click on the empty canvas, and pans the view so the selected step is never hidden behind it. On a narrow canvas it rises from the bottom instead. What goes inside is yours: read the selection with useWorkflowCanvas().selected and compose Koala fields. In the first example every step has a name, a description, settings for its kind, its next steps and a delete action; edits land on the node as you type, filling a step's main setting clears its warning, and every change can be undone.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Right click is built in. On the canvas it offers Tidy up, Fit to screen and Reset to 100%; add your own items on top with menu, or pass menu={false} to turn it off. A node gets its own menu as soon as it has something to offer: Duplicate with onDuplicate, Turn off and on with onDisabledChange, Delete with onDelete, and your items from menu. A node without any falls through to the canvas menu. The same menu opens from a three-dot button in the node's corner, hidden at rest and shown on hover, focus and selection. Build your items from WorkflowMenuItem and its siblings and they appear in both.

Every plus is a WorkflowAddButton, so it can sit inside a DropdownMenu trigger and offer the step types: an output WorkflowPort, a WorkflowEdge and a WorkflowNodeAdd each place their children where their plus goes. WorkflowNodeAdd puts a plus on the left and right of a node (above and below when horizontal) that shows on hover, focus and selection: the place to add a parallel branch under the same parent. In the first example, hover a step or right click it.

Editing the graph is your state's job, so the first example shows the usual moves on plain arrays. A plus on a connection inserts a step between the two nodes and rewires both ends. The side pluses add a parallel branch under the same parent, on that side. Right click a step to do the same, to move it up or down the chain, or to delete it: deleting a step with one parent joins that parent to its children so the chain stays whole. After each change the example calls tidy() through useWorkflowCanvas, and getNode(id) gives a node's live position and size for placing the new one.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Editing#

A few shortcuts for building a workflow quickly, each one reporting back to your state so it can be undone. Double click a branch label such as Yes or No to rename it, or press F2 on a focused connection: Enter saves, Escape cancels, and onLabelChange receives the new name. Drag a node near another node's input or output and the connection is proposed as a dashed draft, made when you let go, through onConnect. Connections can also be drawn from an input port back to an output, except on the trigger that starts the workflow. ⌘C and ⌘V (Ctrl+C and Ctrl+V) copy the selected node and paste it slightly offset, or in the middle of the view when the original is out of sight: the canvas calls onCopyNode and onPasteNode, and your state makes the copy. A resizable node has a handle on its right edge for its width, and edges, fit and Tidy up follow the new size. All of it is on in the first example.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Arranging#

Drag a node and it snaps to the edges and centres of its neighbours, with a thin guide line showing what it lined up with. Hold ⌘ or Ctrl to place it freely, or pass guides={false}. After a lot of moving, Tidy up (the T key, or the button in the controls) lays the whole graph out in layers that follow the connections, branches side by side under their parent, and glides every node to its new place. Changing orientation tidies up on its own, so a workflow can flip between top to bottom and left to right: try the arrows in the first example.

Undo and redo#

Give the canvas onUndo and onRedo and it answers ⌘Z or Ctrl+Z, ⇧⌘Z or Ctrl+Shift+Z, and Ctrl+Y while it has focus, and the controls grow Undo and Redo buttons that follow canUndo and canRedo. The history itself lives with your state: useWorkflowHistory keeps past and future snapshots of whatever you hand it. A drag fires onPositionChange on every frame, so record those as transient and close the step with onPositionCommit, which fires once when the drag ends, after an arrow-key nudge and after Tidy up. One drag, one undo. In the first example, a structural change and the tidy that follows it are a single step too.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Edge style#

Connections are drawn as steps by default: straight runs that turn at a right angle with a 10px rounded corner, so a branching workflow reads as a tidy tree. Pass edgeVariant="curve" on the canvas for soft curves, or variant on one edge to mix them. On a step, the label sits on the turn; on a curve, at its middle.

Logic3 paths
Which plan?

Routes by the account's plan

Action
Send the nurture series
Action
Invite to a workspace
Action
Notify the account owner

Adding steps#

Three ways to grow a workflow without leaving the canvas. Give an output port onAdd and a small plus hangs under it on a short stem: the end of a branch. Give an edge onInsert and a plus appears on it when you hover or tab to it, to put a step in between. A WorkflowNodePlaceholder is a dashed slot for the next step, joined by a dashed edge. All three only call you back: open your own menu of steps, or add one straight away. A step that still needs setting up shows a WorkflowNodeIssue, which also rings the frame, and an empty WorkflowNodeDescription reads No description so every card keeps its height. Hover a connection, or use the dashed slot.

TriggerRecord
Deal moved to Won

In the Sales pipeline

ActionMessage
Notify the account owner

No description

Horizontal#

orientation="horizontal" lays a workflow out left to right: inputs move to the left edge, outputs to the right, and a port's position runs top to bottom. Steps, curves, labels and the add buttons all follow.

TriggerWeb
Form submitted
AgentAI
Score the lead
Logic2 paths
Score above 70?
Action
Assign to sales
Action
Add to nurture

Connecting#

Drag from an output port. The line follows the pointer as a dashed draft and snaps solid once it is close to another node's input, or over the node itself. Let go and onConnect receives { from, to }. Click a connection to select it, then press Delete to remove it. Try connecting the top node to the one on the right.

Trigger
Form submitted
Tool
Enrich the company
Action
Create a CRM record

Run state#

While a run is in flight, set status="running" on the node doing the work and state="running" on the edge leading into it. The edge draws itself from source to target and the input port fills as the step starts: the run reads as one blue line travelling the workflow, and the node at work wears a blue ring. done keeps the travelled path blue and failed turns it destructive. waiting rings a card that needs a person, and disabled dims a step that is switched off. Press Run test below to watch a whole pass.

Runs the workflow once with a sample ticket.

TriggerLive
New ticket

When a ticket arrives

EmailChatWeb form
Agent2 tools
Classify intent

Sets topic and urgency

Knowledge baseOrder lookup
ToolGET
Look up customer

Plan, region and orders

/v1/customers?email={from}
Logic2 paths
Is it urgent?

urgency is High

Action
Page on-call

Pings the support rota

Action
Draft a reply

For an agent to review

Trigger
Refund requested
Agent
Check the order

Waiting for approval

Tool
Issue the refund

Provider returned 502

Action
Email the customer

Turned off for this run

Drag the empty canvas to pan, or hold Space and drag anywhere. The wheel pans; ⌘ or Ctrl with the wheel, and a trackpad pinch, zoom towards the pointer. With the canvas focused, the arrow keys pan, + and − zoom, 0 returns to 100% and ⇧1 fits every node, T tidies up, ⌘Z and ⇧⌘Z undo and redo. V and H switch between the select and hand tools. Nodes and edges are in the tab order: Enter selects, Delete removes, and the arrow keys move a focused node by 5px (20px with Shift). ⌘C and ⌘V copy and paste the selected node, F2 renames a focused branch. Escape clears the selection or cancels a connection.

API reference#

WorkflowCanvas

The root: a focusable viewport with a dotted ground. It owns pan, zoom, selection and the connection you are drawing. Nodes and edges render inside its world layer; WorkflowControls stays fixed on top. Forwards native <div> props.

PropTypeDefaultDescription
viewport{ x: number; y: number; zoom: number }-Pan and zoom, controlled.
defaultViewport{ x: number; y: number; zoom: number }{ x: 0, y: 0, zoom: 1 }The initial pan and zoom. Ignored while fitView frames the nodes.
onViewportChange(viewport: WorkflowViewport) => void-Called on every pan and zoom.
fitViewbooleantrueFrame every node once they have been measured, never above 100%.
tool"select" | "hand"-The tool in hand, controlled.
defaultTool"select" | "hand""select"The initial tool. hand pans on any drag, nodes included.
onToolChange(tool: WorkflowTool) => void-Called when the tool changes.
selectedstring | null-The selected node or edge id, controlled.
defaultSelectedstring | nullnullThe initially selected id.
onSelectedChange(id: string | null) => void-Called when the selection changes.
onConnect(connection: { from: string; to: string }) => void-Called when a connection is dropped on a node, drawn from either end, or when a dragged node is let go next to another. Add a WorkflowEdge for it: the canvas never adds one itself.
proximityConnectbooleantrueWhile onConnect is set, dragging a node near another's input or output proposes the connection as a dashed draft and makes it on drop.
onCopyNode(id: string) => void-Called on ⌘C or Ctrl+C with the selected node's id. Keep its data yourself: the canvas only remembers which node it was.
onPasteNode(position: WorkflowPosition) => void-Called on ⌘V or Ctrl+V after a copy, with where the copy's top-left corner should go: 40px down and right of the original, a little further on each paste, or the middle of the view when that would land off screen.
minZoomnumber0.25The furthest you can zoom out.
maxZoomnumber2The closest you can zoom in.
wheel"pan" | "zoom" | "none""pan"What the wheel does. ⌘ or Ctrl with the wheel, and a trackpad pinch, always zoom. none leaves the page scrolling.
orientation"vertical" | "horizontal""vertical"Which way the workflow flows. Moves the ports to top and bottom, or left and right.
edgeVariant"step" | "curve""step"How every edge is drawn unless it sets its own variant.
guidesbooleantrueSnap a dragged node to its neighbours' edges and centres, with a guide line. ⌘ or Ctrl skips it for one drag.
onUndo() => void-Called on ⌘Z or Ctrl+Z. Also adds Undo and Redo buttons to the controls.
onRedo() => void-Called on ⇧⌘Z, Ctrl+Shift+Z or Ctrl+Y.
canUndobooleantrueEnables the Undo button.
canRedobooleantrueEnables the Redo button.
menuReact.ReactNode | false-Extra items at the top of the canvas's right-click menu (Tidy up, Fit to screen, Reset to 100%). false turns the menu off.
onDropStep(value: string, position: WorkflowPosition) => void-Called when a WorkflowPaletteItem is dropped on the canvas, with its value and where the node's top-left corner should go.
Data attributeDescription
data-toolselect or hand.
data-panningPresent while the canvas is being dragged.
data-spacePresent while Space is held for a temporary hand.
data-wiringout or in while a connection is being drawn, from an output or from an input.
data-proposingPresent while a dragged node proposes a connection.
CSS variableDescription
--workflow-node-widthThe width of every node. Defaults to 15rem.
--workflow-inkThe colour of an idle connection.

WorkflowNode

A card on the canvas, placed by its top-left corner. Drag it, or focus it and move it with the arrow keys. Forwards native <div> props.

PropTypeDefaultDescription
id*string-Unique in the canvas. Edges point at it. No colons.
kind"trigger" | "agent" | "tool" | "logic" | "action""action"What the step is. Sets the label's text and dot.
position{ x: number; y: number }-The position, controlled.
defaultPosition{ x: number; y: number }{ x: 0, y: 0 }The initial position.
onPositionChange(position: WorkflowPosition) => void-Called while the node is dragged or nudged, on every frame.
onPositionCommit(position: WorkflowPosition) => void-Called once a move is finished: at the end of a drag, after a nudge and after Tidy up. Close an undo step here.
status"idle" | "running" | "done" | "waiting" | "failed""idle"Run state. running lights the input port, waiting and failed ring the card.
disabledbooleanfalseDims the card for a step that is switched off.
draggablebooleantrueWhether it moves with the pointer and the arrow keys.
labelstring-The node's accessible name, usually its title.
onDelete() => void-Called on Delete or Backspace while the node has focus, and from Delete in its right-click menu.
onDuplicate() => void-Adds Duplicate to the node's right-click menu.
onDisabledChange(disabled: boolean) => void-Adds Turn off / Turn on to the node's right-click menu.
menuReact.ReactNode | false-Your own items at the top of the node's menu. Build them from WorkflowMenuItem and its siblings so they show in the right-click menu and the three-dot menu alike. false turns both off.
menuButtonbooleantrueShows a three-dot button in the node's top-right corner, on hover, focus and selection, that opens the same menu as right click. It takes the meta's place while it shows.
resizablebooleanfalseAdds a handle on the right edge to change the node's width by dragging, or with the arrow keys once it has focus (Shift for bigger steps).
widthnumber-The width in pixels, controlled. Edges, fit and Tidy up follow it.
defaultWidthnumber--workflow-node-widthThe initial width.
onWidthChange(width: number) => void-Called while the node is resized.
onWidthCommit(width: number) => void-Called once a resize is finished. Close an undo step here.
minWidthnumber160The narrowest the handle goes.
maxWidthnumber640The widest the handle goes.
Data attributeDescription
data-kindThe node's kind.
data-statusThe node's status.
data-selectedPresent while the node is selected.
data-draggingPresent while the node is being dragged.
data-snapPresent while a connection being drawn, or proposed by a drag, will land on this node.
data-actionsPresent when the node has a three-dot menu.
data-resizingPresent while the node is being resized.
CSS variableDescription
--workflow-frameThe frame's tint, always a step below the sheet: --muted in light and cream, --background in dark and moonlight.

WorkflowNodeLabel

The frame's top line: the kind's dot and name, then a meta on the right. While the node has a status other than idle, a 14px mark takes the meta's place: a spinner, a check, a hand or a warning. Children replace the kind's name.

PropTypeDefaultDescription
metaReact.ReactNode-A short fact for the right edge: GET, 2 tools, Step 3.

WorkflowNodeBody

The sheet set 4px into the frame, with concentric corners. Holds the header, description and content.

WorkflowNodeHeader

A 20px row for the icon and the title.

WorkflowNodeIcon

The step's glyph, 16px and muted. When present, the description and content line up under the title.

WorkflowNodeTitle

The step's name, on one line.

WorkflowNodeDescription

One muted 12px line under the header. Left empty, it reads No description in italics and sets data-empty.

WorkflowNodeIssue

A warning line at the foot of the sheet for a step that still needs setting up. Its presence rings the frame. Announced as a status.

WorkflowNodePlaceholder

A dashed button that fills the node: the slot for the next step. The node drops its frame around it. Defaults to a plus and Add a step. Forwards native <button> props.

WorkflowNodeContent

One line of details under the description: chips, an endpoint, a condition. It fades out at the right edge instead of wrapping.

WorkflowPort

A connection point. Inputs sit on the top edge, outputs on the bottom. Drag from an output to draw a connection. Without any port, edges still meet the middle of the edge.

PropTypeDefaultDescription
type*"in" | "out"-Which edge of the card it sits on.
idstringthe typeNames an extra output, so an edge can leave from it: from="plan:pro".
positionnumber0.5Where along the edge, from 0 to 1: left to right, or top to bottom when horizontal.
onAdd() => void-Outputs only. Hangs a small plus button off the port on a short stem, for the end of a branch.
connectablebooleantrue, false on a trigger's inputWhether a connection can be dragged from it. An input connects backwards to an output; the trigger that starts a workflow keeps its input fixed.
Data attributeDescription
data-typein or out.
data-activePresent on both ends of the connection being drawn or proposed.
data-connectablePresent when a connection can be dragged from the port.

WorkflowEdge

A curved connection from one node's output to another's input. It has a wide invisible hit area, is focusable, and sits under the nodes. Forwards native <svg> props.

PropTypeDefaultDescription
from*string-The source node id, or node:port for a named output.
to*string-The target node id.
idstring${from}->${to}The id used for selection.
labelReact.ReactNode-A small chip at the curve's midpoint: Yes, No.
state"idle" | "running" | "done" | "failed""idle"running draws the line from source to target; done and failed tint it.
onDelete() => void-Called on Delete or Backspace while the edge has focus.
onInsert() => void-Shows a plus on the edge on hover and focus (always on touch), to insert a step in between.
onLabelChange(label: string) => void-Makes a text label renamable: double click it, or press F2 on the focused connection, and it turns into a field. Enter or a click away saves, Escape cancels.
variant"step" | "curve"the canvas'sOverrides the canvas's edgeVariant for this edge.
dashedbooleanfalseA dashed line, for an edge into a placeholder.
aria-labelstring-Replaces the default Connection from a to b, which uses the ids.
Data attributeDescription
data-stateThe edge's state.

WorkflowAddButton

The plus that adds a step: an outline, icon-only Button at xs, the house rounded square. Rendered on its own by onAdd and onInsert; pass it as a child of an output WorkflowPort, a WorkflowEdge or a WorkflowNodeAdd (usually inside a DropdownMenuTrigger asChild) and it takes the same place. Forwards Button props.

WorkflowNodeAdd

A plus beside a node, shown on hover, focus and selection: left or right, or above and below when horizontal. Children replace the default WorkflowAddButton, for a menu of step types.

PropTypeDefaultDescription
side*"before" | "after"-Left or right of the node (above or below when horizontal).
onAdd() => void-Called by the default button.

WorkflowInspector

The settings panel, docked to the right of the canvas above the nodes (a bottom sheet on canvases narrower than 34rem). Shows while a node is selected and pans that node into view. Forwards native <aside> props.

PropTypeDefaultDescription
openbooleana node is selectedShow or hide the panel yourself.

WorkflowInspectorHeader

The title row, with a close button that clears the selection.

WorkflowInspectorIcon

The step's glyph for the header, in a 32px well with the node frame's tint and a hairline, so it reads on the panel in every theme.

WorkflowInspectorBody

The scrolling content.

WorkflowInspectorSection

A group of fields under a small heading.

PropTypeDefaultDescription
labelReact.ReactNode-The heading: Settings, Next steps.

WorkflowInspectorFooter

A muted well for the panel's actions, such as Delete and Done.

WorkflowPalette

The floating steps panel, docked to the left of the canvas above the nodes. Holds the parts below. On canvases narrower than 60rem it folds behind a Steps button in the controls, and hides while the settings panel is open there. Forwards native <div> props.

WorkflowPaletteHeader

The panel's title row. Defaults to Steps.

WorkflowPaletteSearch

A small search field that filters the rows by value and keywords. Forwards native <input> props.

WorkflowPaletteList

The scrolling list of groups. Shows No steps found when the search matches nothing.

WorkflowPaletteGroup

A labelled group of rows. Hides itself when the search leaves it empty.

PropTypeDefaultDescription
labelReact.ReactNode-The group's heading: Conditions, Tasks.

WorkflowPaletteItem

A row you can click or drag onto the canvas. Forwards native <button> props.

PropTypeDefaultDescription
value*string-What the row adds. Passed to onSelect and to the canvas's onDropStep, and matched by the search.
keywordsstring[]-More words the search should match.
onSelect(value: string) => void-Called on click and on Enter.

WorkflowMenuItem

An item for a node's menu that renders as a ContextMenuItem on right click and as a DropdownMenuItem in the three-dot menu. WorkflowMenuSeparator, WorkflowMenuLabel, WorkflowMenuShortcut, WorkflowMenuSub, WorkflowMenuSubTrigger and WorkflowMenuSubContent follow the same rule. Takes the props of the item it becomes.

useWorkflowHistory

useWorkflowHistory(initial, { limit }) keeps undo and redo snapshots of any state (100 by default). Returns state, set(next, { transient }), commit(), undo(), redo(), reset(state), canUndo and canRedo. Transient sets replace the present without a new step until commit().

useWorkflowCanvas

A hook for anything rendered inside the canvas, such as a context menu: returns zoom, tool, setTool, selected, select, zoomBy, zoomTo, fitView, tidy, viewportCenter, getNode(id) and revealNode(id) (a node's live x, y, width and height).

WorkflowControls

A floating Toolbar fixed to the bottom of the canvas: select and hand tools, zoom out, the zoom level (click for 100%), zoom in, fit, Tidy up and Expand, which lifts the canvas over the page with every panel docked (Escape puts it back). A Steps button leads when there is a steps panel, Undo and Redo when the canvas has a history. Children are appended after a separator. Forwards Toolbar props.

FAQ#

No. Every node has a position you choose, so the layout is yours and stays where people put it. If you need automatic layout, run a layout library over your nodes and pass the results as positions.