--- meta: title: Flow Builder description: A drag-and-drop visual automation builder with a steps panel, a pan/zoom canvas, and a configuration inspector. Extend it with your own node types via a JS registry. layout: component fullWidth: true --- The Flow Builder is a three-panel editor for visual automations, with an optional header action bar: - **Header** (optional) — a full-width action bar rendered only when `slot="header-left"` / `slot="header-right"` content is provided (e.g. Close / Undo All Changes on the left, Apply Changes on the right). - **Left panel** — the steps panel (searchable, tabbed by step group). - **Canvas** (center) — a pannable, zoomable surface. A node's branches fan out along a bus below it, spaced by what they actually hold: two branches with children keep a full card lane apart, while a branch that is only a pill sits close in, so declaring branches you have not wired costs little room. Wires never run through a card: a branch that reaches past the next row keeps its pill on its own bus and takes its wire out around the outside of whatever it flies over, so it always reads as ending where it ends. Connections are **append-only**: click any **output port** on a node to start a **stray branch** — the wire follows your cursor until you click a node (or its output port) to attach it. Fan-in is allowed, and so are **loops** — a branch may point back to an earlier step (e.g. an answer that restarts the questioning); only wiring a node directly to itself is refused. Cancel by clicking empty canvas, pressing Esc, or leaving the window. A connected output port spawns a brand-new branch on click, so extra arrows never require config forms. Open outputs draw nothing while idle — their **`+`** targets appear only while dragging a step in or moving one. Every existing wire has a **`+`** at its midpoint to insert a step between two nodes. New steps are created by dragging them from the panel onto the canvas or a `+`. Reposition nodes by dragging, and add resizable sticky notes. Scroll to pan (side-scroll or Shift+scroll pans horizontally); Ctrl/Cmd+scroll or trackpad pinch zooms toward the cursor. Toolbar: undo, redo, add-note, **untangle** (auto-arranges a messy flow into evenly spaced layers that follow the connections — undoable), zoom-in, reset, zoom-out. - **Right panel** — the sidebar by default: a slot (`slot="sidebar"`) for status / version history, with a built-in Configuration Errors summary derived from `errorNodes`. Selecting a node slides that step's configuration in from the right (driven by the node type's `renderConfig`); clicking a **branch pill** on a wire slides in the branch editor instead — rename the branch and configure the filters/conditions for taking that path. Node types that declare **`branchFilters`** (in markup or JS) get the built-in conditions editor — pick filters from a searchable list and combine them into AND groups joined by OR, saved onto the output port's `data.conditions`. A custom `renderBranchConfig` takes precedence when supplied. Both side panels can be **tucked away** with the chevrons on the canvas edges, giving the canvas the full width; selecting a node or branch brings the right panel back automatically. A node's **`…`** menu offers Delete, Duplicate, and **Move** — Move detaches the step (with its subtree) so you can re-attach it to a different `+` slot. Every node except an entrypoint (a node with `inputs=""`) can have as many inputs and outputs as it likes — outputs are per-node overridable, so a step's config can add and remove branches at runtime. It ships with **no built-in node types** — every step you see below is registered by the consumer. This keeps the component generic and lets it be extended for any future workflow without changing the library. Open the full-page demo Open the Troubleshoot Q&A demo ```html:preview

Cancellation Requested

Contact added manually

Contact added to a list

IMAP Email Parser

Send Reply

Claude

Notify User

Conditional Split

``` ## Examples ### Empty builder With no node types registered, the steps panel is empty. Register types to populate it. ```html:preview

``` ### Declaring the steps panel The builder owns the steps panel: **Entrypoints / Triggers / Actions / Rules** tabs with a search box. You don't author the tabs or their layout — you just declare the node types, and each is routed to the right tab by its `group` and grouped under a collapsible `category`. A tab only renders when its group has at least one registered step, so unused groups never appear. Declare each type as a `` (the items themselves are never shown — they're declarations that drive the rendered panel): - `type` (required) — the node type id. - `group` — `entrypoint` | `trigger` | `action` | `rule`; picks the tab (defaults to `action`). - `category` — collapsible group within the tab (e.g. "Email"). - label — the slotted text (or a `label` attribute). - `icon`, `icon-library`, `color`, `description`. - `inputs` — a JSON array of input ports. Omit for a single default input; use `inputs=""` for a trigger with no input. - `outputs` — a JSON array of ports, each a string id or a `{"id","label"}` object (e.g. `outputs='[{"id":"true","label":"TRUE"},{"id":"false","label":"FALSE"}]'`). Omit for a single default output. - `fixed-outputs` — the declared outputs are the *only* branches this step has: their pills carry no delete, and clicking a fully-wired node's output adds nothing. Use it when the branches mirror fixed fields in your own model (a success / failure / skip triple, say), where an extra or missing branch has nowhere to be stored. Branches a step declares but has not wired cost almost no room — they are spaced by their pill rather than by a whole child lane — so a step can offer every branch it supports without fanning empty lanes across the canvas. Set an optional per-tab hint with the `triggers-hint` / `actions-hint` / `rules-hint` attributes on the builder. (A node's inspector `renderConfig` can't be expressed in markup — supply it via `registerNodeTypes()` for the same `type` id if you need a custom config panel. Branch conditions *can* be expressed in markup — see the next section.) ```html

Cancellation Requested

Conditional Split

``` ### Branch conditions in markup Clicking a **branch pill** opens the branch editor. For step types that declare **branch filters**, it renders the built-in conditions editor: a searchable filter picker, then the picked filters combined into **AND groups joined by OR** — with Save / Cancel, so edits only apply (undoably) on Save. Declare the filters when instantiating the builder by nesting `` elements inside a `` (use the `label` attribute for the step's name when nesting). Each filter holds one `` per control row, and each field declares its choices as nested `` / `` elements — the element text is the label, with an optional `value` attribute for the stored value. Try it: click the **High intent** or **Everyone else** pill to open the conditions editor. ```html:preview

Cancellation Requested

at least

at most

exactly

in the last

before the last

day(s)

week(s)

month(s)

Is equal to

Is not equal to

Price

Competitor

No need

Other

is not

Starter

Growth

Enterprise

within the last

more than

contains

does not contain

Send Win-back Offer

Notify Account Manager

``` `` attributes: `id` (required), `label`, `description` (shown under the label in the picker). `` attributes: - `id` (required) — key the field's operator/value are stored under. - `type` — `select` | `number` | `text`. Defaults to `select` when options are given, else `text`. - `suffix` — trailing unit text (e.g. `time(s)`) when the unit isn't adjustable. - `label`, `placeholder`, `value` (the initial value when the filter is added). Inside a field, `` elements declare the operator dropdown (shown before the value — "at least", "is equal to"), `` elements the value choices of a `select` field, and `` elements an **adjustable unit dropdown** after the value (day(s) / week(s) / month(s)) — so a row can have three adjustable controls: operator, amount, and time frame. The element text is the display label; add `value="…"` to store a stable key instead of the text. Empty operators with a **well-known key** get a default label — `` renders as "Greater Than or Equal To". Recognised keys: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `is`, `is-not`, `in`, `not-in`, `contains`, `not-contains`, `starts-with`, `ends-with`, `empty`, `not-empty`, `within`, `before`, `between`, `matches`. For programmatic generation the same lists also fit in `operators` / `options` **attributes** (comma-separated values, or a JSON array of strings and/or `{"value","label"}` objects), a whole catalog fits in a **`branch-filters` JSON attribute** on the step, and JS registration takes a `branchFilters` array on the `FlowNodeType` — as in the full demo at the top of this page. A type supplying its own `renderBranchConfig` overrides the built-in editor. Saved conditions live on the output port as `port.data.conditions`, an array of OR-ed groups, each an array of AND-ed conditions: ```js [ [ // group 1 (AND-ed)… {filter: 'engagement', values: {count: {operator: 'gte', value: 2}, window: {operator: 'within', value: 6, unit: 'months'}} }, {filter: 'lost-reason', values: {reason: {operator: 'eq', value: 'price'}}} ], // …OR group 2 [{filter: 'arr', values: {amount: {operator: 'gte', value: 5000}}}] ] ``` ### Registering custom node types Node types are the modular extension point. Instead of (or alongside) slotted steps, register an array of `FlowNodeType` objects with `registerNodeTypes()` (or set the `.nodeTypes` property) — the two sources merge into the same panel. Each type's `group`/`category` place it in the tabs; its icon, color, input/output ports, and optional `renderConfig` define the node's behavior and inspector. ```js import {html} from 'lit'; const builder = document.querySelector('zn-flow-builder'); builder.registerNodeTypes([ { type: 'send-email', label: 'Send Email', group: 'action', // 'trigger' | 'action' | 'rule' — which steps-panel tab category: 'Email', // collapsible group within the tab icon: 'mail@lu', color: 'rgb(43, 192, 145)', defaultData: {subject: ''}, // Inspector UI for a selected node of this type: renderConfig: (node, update) => html` update({subject: e.target.value})}> `, }, { type: 'ab-split', label: 'A/B Split', group: 'rule', icon: 'split@lu', // Multiple outputs become labelled connection points (TRUE / FALSE here): outputs: [{id: 'true', label: 'TRUE'}, {id: 'false', label: 'FALSE'}], }, ]); ``` A node type with `inputs: []` is a starting point (a trigger) with no incoming port. A type with multiple `outputs` renders one labeled port per output, so a branch can fan out to different steps. Add **`fixedOutputs: true`** when those outputs are the only branches the type can have — the canvas drops the delete on their pills and refuses to materialise an extra one. Unwired branches are spaced by their pill rather than a child lane, so a type can declare its full set of branches up front without the canvas fanning empty lanes for the ones a given node is not using. #### User-configurable outputs A type's `outputs` are the default. For steps whose branches are defined by the user (e.g. a conditional split), set **`node.outputs`** on the instance from `renderConfig` — the canvas renders those ports, and the builder prunes any connection whose branch is removed. `node.inputs` works the same way. Set the new ports then call `update({})` to commit: ```js renderConfig: (node, update) => { const branches = node.outputs ?? [{id: 'true', label: 'TRUE'}, {id: 'false', label: 'FALSE'}]; const addBranch = () => { node.outputs = [...branches, {id: crypto.randomUUID(), label: 'New branch'}]; update({}); // commit — re-renders the outputs, prunes dropped branches' connections }; // …render an editor for `branches` that calls addBranch / removes / renames… } ``` ### Reacting to changes The builder emits events as the flow is edited. Use `zn-flow-change` to persist, or read `.value` (a JSON string of the full `FlowState`) at any time. ```js const builder = document.querySelector('zn-flow-builder'); builder.addEventListener('zn-flow-change', e => { console.log('flow updated', e.detail.state); }); builder.addEventListener('zn-flow-selection-change', e => { console.log('selected node', e.detail.nodeId); }); builder.addEventListener('zn-flow-connect', e => { console.log('new connection', e.detail.connection); }); // Persist / restore — `value` is the full FlowState, node positions included: localStorage.setItem('flow', builder.value); builder.value = localStorage.getItem('flow'); // Saving to a server: the builder serialises directly (toJSON returns the // FlowState), so the POST body is one expression either way: await fetch('/api/flows/123', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(builder), // === builder.value }); ``` ### Auto-save Add the `auto-save` attribute to periodically snapshot the flow (positions included) into localStorage, keyed by the builder's `id` (falling back to its `heading`), with a **1-day TTL**: ```html

``` Without the attribute nothing is saved. An empty canvas is never written (so a fresh session can't clobber a stored flow), and expired snapshots are purged when encountered. While auto-save is on, a **status pill** in the canvas's bottom-left flashes "Auto-saved" as each snapshot lands and otherwise shows how long ago the last one happened ("Last saved 3m ago"). And when a flow is loaded (`setState` / `value`) that **differs from a fresh auto-saved draft**, a banner offers to restore the draft — editing the loaded flow or dismissing the banner keeps what was loaded. Restoring can also be done programmatically: ```js const builder = document.querySelector('zn-flow-builder'); if(builder.restoreAutoSave()) { console.log('Restored an auto-saved draft'); // false when none exists / it expired } ``` Try it below — the demo saves every **6 seconds** (`auto-save="0.1"`; real flows would use minutes). Drag a node and watch the pill flash **Auto-saved**. Then **reload the page**: the demo always loads its original flow, so if your draft differs a banner offers to restore it. ```html:preview

Order Placed

Send Confirmation

Notify Team

```

Version History