# Flowchart
> Two workflow steps on a dotted board, a trigger and an If / Else, joined by a curve that follows them as they are dragged.
A trigger card, “New order created”, joined by a soft curve to an If / Else step whose conditions read as a sentence of chips: if order flavor is Rocky Road, and order topping is… Drag either step about the board and the curve follows in the same frame; select the trigger and its ring and the curve turn blue. Every field and value chip opens a small menu over itself, with one highlight gliding between the options.
A React component by Bruno Delorence: https://brunodelorence.com/components/flowchart. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: AI.
## Anatomy
1. **Board**: A dotted surface, dots every 22 px. It grows when narrow cards make the conditions wrap.
2. **Step tag**: Names the kind of step over its card, tinted in its hue: violet for a trigger, amber for If / Else.
3. **Trigger**: A card that can be selected: a click turns its ring and the curve to the accent. Dragging it moves it instead.
4. **Curve**: Joins the two cards’ facing edges, its handles standing off by 0.55 of the drop. Redrawn in the same frame as a move.
5. **If / Else card**: The conditions, a row each, read top to bottom as one sentence.
6. **Subject**: The object the condition reads, raised like a button. It does not open a menu.
7. **Field chip**: The field compared. Opens a menu of the other fields; Enter, Space or the arrows open it from the keyboard.
8. **Value chip**: The value it must have, with its colour dot. Drops to a line of its own, under the subject, when the row is full.
## When to use
- Showing how an automation runs: a trigger, then the step that decides what happens next.
- Rules that read best as a sentence: “If order flavor is Rocky Road, and order topping is …”.
- Conditions picked from short, known lists (fields and their values), each a chip with a menu.
- A builder where people arrange the steps themselves, by dragging them or with the arrow keys.
## When not to use
- Long workflows with many branches and loops. Use a full canvas with zoom, pan and auto layout.
- A single rule with no trigger to show. A filter row or a form says it in less room.
- Values typed freely (amounts, dates, text). The chips only pick from lists; use real inputs.
- A read-only diagram that nobody edits. Draw it as a static figure.
## Installation
Install it with the shadcn CLI, into components/flowchart of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/flowchart.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19.2 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { Flowchart, type Condition } from './flowchart';
export function OrderRule({ rule, onSave }: { rule: Condition[]; onSave: (rule: Condition[]) => void }) {
return (
);
}
```
## States
- **Resting**: Both steps in place, nothing selected: the curve is a grey hairline.
- **Trigger selected**: A 1.5 px accent ring, and the curve in the accent too, eased over 150 ms.
- **Step moved**: Dragged off its place, the trigger comes to the front and the curve bends to follow.
- **Field menu open**: The chip stays filled while its menu is open; the check marks the current field.
- **Value menu, highlighted**: The highlight glides to the option under the pointer or the arrow keys, 220 ms.
- **Narrow**: A long value gets a line of its own, lined up under the subject, and the board grows.
## How it works
- Each step is placed by its left (its middle, from the board’s centre) and its top. A press anywhere on a step but its chips becomes a drag after 3 px, and only then captures the pointer, so a press that stays put still clicks the card under it. Steps stay 8 px inside the board, and the one last moved comes to the front.
- The curve runs from the middle of the trigger card’s bottom edge to the middle of the If / Else card’s top edge: a cubic Bézier whose two handles stand off vertically by 0.55 of the drop. It is measured from the cards themselves in a layout effect, so it is redrawn before the frame that moved them is painted.
- Selecting the trigger swaps its shadow for a 1.5 px accent ring, and the curve’s stroke eases to the accent in 150 ms. Hovering a card raises its shadow in 150 ms; every shadow is written with the same nine layers, so the browser can ease between them.
- A menu pops in over its chip in 180 ms (a 0.95 scale and a fade, on cubic-bezier(0.23, 1, 0.32, 1)) from the chip’s corner: the left one, or the right one when it would pass the card’s edge; it opens under the chip when the board has no room above. It is placed in a layout effect, before it is ever painted.
- One highlight glides between the options (220 ms on its top) under the pointer or the arrow keys, and fades away when the pointer leaves the menu. The chosen option keeps a check.
- A condition’s value sits on its row when it fits, and otherwise drops to a line of its own, lined up under the subject chip; on a narrow board the card wraps and the board grows to keep 24 px under it.
- While on screen and untouched, a demo pointer selects the trigger, drags it off and back, then picks another flavour and topping and puts the first ones back. Any input of the reader’s hands it over.
- Every colour is a light-dark() token on the root, so the board follows the page’s color-scheme or the colorScheme prop. The two step hues, violet and amber, are mixed into each scheme’s surface with color-mix(), so their tags and icon tile are tuned for both.
## API reference
- **trigger** (`{ tag: string; title: string; description: string }`, default `New order created`): The first step: its tag, its title and the line under it.
- **branchTag** (`string`, default `'If / Else'`): The tag over the conditions.
- **defaultConditions** (`Condition[]`, default `flavour and topping`): The rows it starts with: { id, joiner, subject, field, fields, value, values: { label, note?, color? }[], valuesWidth? }.
- **onConditionsChange** (`(conditions: Condition[]) => void`): Called with every condition after a field or a value is picked.
- **defaultMenu** (`FlowchartMenu | null`): A condition’s menu open from the start: row, slot ('field' or 'value') and active, the option under the highlight. It closes as usual. Setting it turns the demo off.
- **defaultSelected** (`boolean`, default `false`): Whether the trigger starts selected.
- **onSelectedChange** (`(selected: boolean) => void`): Called when the trigger is selected or cleared.
- **draggable** (`boolean`, default `true`): The steps can be dragged about the board, and a focused trigger moved with the arrow keys.
- **defaultOffsets** (`Partial>`): How far each step starts from its place, in px. Setting it turns the demo off.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a demo pointer selects and drags the trigger and picks other values.
- **colorScheme** (`'light' | 'dark' | 'system'`): Its colours: light, dark, or the reader’s system setting. Without it the component follows the page’s color-scheme, which is light unless the page sets one.
- **className** (`string`): Extra class for the root.
## Accessibility
- The trigger is a toggle button (aria-pressed). Focused, the arrow keys move it 4 px at a time, or a dot’s width (22 px) with Shift; a visually hidden hint says so.
- Each field and value chip is a button with aria-haspopup="listbox" and a name that says what it holds (“order flavor: Rocky Road”). Enter, Space or the arrows open its menu, a listbox that takes the focus and marks its active option with aria-activedescendant; Home and End jump, Enter or Space picks, Escape closes and returns to the chip, Tab closes and moves on.
- A press outside an open menu closes it. A choice is announced in a polite live region (“order topping is Hot fudge”).
- The conditions card is a labelled group; the curve, the grips and the icons are decorative (aria-hidden).
- Under reduced motion menus appear at once, the highlight and the shadows do not ease, and the demo never plays.
## Source
### flowchart/flowchart.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useCallback,
useEffect,
useId,
useLayoutEffect,
useRef,
useState,
type KeyboardEvent as ReactKeyboardEvent,
type PointerEvent as ReactPointerEvent,
} from 'react';
import { DemoPointer, runDemo, type Point } from './demo-pointer';
import { useAutoplay } from './use-autoplay';
import styles from './flowchart.module.css';
/*
* Flowchart: two steps of a workflow on a dotted board. A trigger ("New order created") is joined
* by a curve to an If / Else step whose conditions read as a sentence of chips: "If order flavor
* is Rocky Road, and order topping is ...". The field and the value chips open menus.
*
* - Each step is placed by its left (its middle, from the board's centre) and its top. Pressing a
* step anywhere but on a chip and moving more than 3 px drags it, kept inside the board; the step
* last dragged comes to the front. A press that does not move selects or clears the trigger.
* - The curve runs from the middle of the trigger card's bottom edge to the middle of the If / Else
* card's top edge: a cubic whose handles stand off vertically by 0.55 of the drop. It is
* measured from the cards themselves and rewritten in the same frame as anything that moves
* them, so it never lags. A selected trigger turns its ring and the curve to the accent.
* - A menu opens over its chip (under it when the board has no room above), from the chip's
* corner nearest its text: the left one, or the right one for a chip in the right half of its
* card. One highlight glides between the options, under the pointer or the arrow keys.
* - A condition's value sits on the row when it fits, and otherwise on a line of its own, lined up
* under the subject chip. The board grows when narrow cards make the conditions wrap.
* - While on screen and untouched, a demo pointer selects the trigger, drags it about, and picks
* other flavours and toppings, then puts them back.
* - Light or dark: every colour is a light-dark() token in the CSS, so the scheme is the page's
* color-scheme, or the one the colorScheme prop sets.
*/
export type ConditionOption = {
label: string;
/** A word after the label, in a fainter ink (the flavour's range, say). */
note?: string;
/** The dot before the label, on the chip. */
color?: string;
};
export type Condition = {
id: string;
/** The first word of the row: "If", then "and" or "or". */
joiner: string;
/** The object the condition reads, in the chip after the joiner. */
subject: string;
/** The field it compares, one of `fields`. */
field: string;
fields: string[];
/** The value it must have, one of `values` by label. */
value: string;
values: ConditionOption[];
/** The width of the values' menu, in px; by default as wide as its widest option. */
valuesWidth?: number;
};
export type FlowchartTrigger = { tag: string; title: string; description: string };
const AMBER = '#f09a2f';
const FLAVORS: ConditionOption[] = [
{ label: 'Rocky Road', note: 'Classic', color: AMBER },
{ label: 'Mint Chip', note: 'Classic', color: AMBER },
{ label: 'Pistachio', note: 'Seasonal', color: AMBER },
{ label: 'Bubblegum', note: 'Retro', color: AMBER },
];
const TOPPINGS: ConditionOption[] = [
{ label: 'Brown butter bourbon brittle crunch', color: AMBER },
{ label: 'Rainbow sprinkles', color: AMBER },
{ label: 'Hot fudge', color: AMBER },
{ label: 'Candied pecans', color: AMBER },
];
const FIELDS = ['flavor', 'topping', 'size', 'scoops'];
const TRIGGER: FlowchartTrigger = {
tag: 'Trigger',
title: 'New order created',
description: 'Trigger when a new order is created',
};
const CONDITIONS: Condition[] = [
{
id: 'flavor',
joiner: 'If',
subject: 'order',
field: 'flavor',
fields: FIELDS,
value: 'Rocky Road',
values: FLAVORS,
valuesWidth: 176,
},
{
id: 'topping',
joiner: 'and',
subject: 'order',
field: 'topping',
fields: FIELDS,
value: 'Brown butter bourbon brittle crunch',
values: TOPPINGS,
valuesWidth: 256,
},
];
/** The steps' tops on the board, their widths at most, and the board's height at least. */
const TRIGGER_TOP = 24;
const BRANCH_TOP = 174;
const TRIGGER_WIDTH = 300;
const BRANCH_WIDTH = 356;
const BOARD_HEIGHT = 333;
/** Room kept under the last step when the board grows, and around a step on a narrow board. */
const MARGIN = 24;
/** How close to the board's edges a step may be dragged. */
const INSET = 8;
/** How far a press must move to become a drag. */
const SLOP = 3;
/** The handles of the curve stand off by this share of its drop. */
const BEND = 0.55;
type NodeId = 'trigger' | 'branch';
type Slot = 'field' | 'value';
type Menu = {
row: number;
slot: Slot;
/** The option under the highlight, and whether the highlight shows. */
active: number;
shown: boolean;
};
const ZERO: Record = { trigger: { x: 0, y: 0 }, branch: { x: 0, y: 0 } };
/** A menu to open with: its row, its chip, and the option under the highlight (none: no highlight). */
export type FlowchartMenu = { row: number; slot: Slot; active?: number };
/** The open menu a FlowchartMenu describes, its highlight on `active` or resting on the choice. */
const menuOf = (conditions: Condition[], start: FlowchartMenu | null | undefined): Menu | null => {
const condition = start ? conditions[start.row] : undefined;
if (!start || !condition) return null;
const labels =
start.slot === 'field' ? condition.fields : condition.values.map((option) => option.label);
const current = Math.max(
0,
labels.indexOf(start.slot === 'field' ? condition.field : condition.value),
);
return {
row: start.row,
slot: start.slot,
active: start.active ?? current,
shown: start.active !== undefined,
};
};
export function Flowchart({
trigger = TRIGGER,
branchTag = 'If / Else',
defaultConditions = CONDITIONS,
onConditionsChange,
defaultSelected = false,
onSelectedChange,
draggable = true,
autoplay = true,
colorScheme,
defaultMenu,
defaultOffsets,
className = '',
}: {
/** The first step: its tag, title and line under it. */
trigger?: FlowchartTrigger;
/** The tag over the conditions. */
branchTag?: string;
/** The conditions it starts with, a row each. */
defaultConditions?: Condition[];
/** Called with every conditions after a field or a value is picked. */
onConditionsChange?: (conditions: Condition[]) => void;
/** Whether the trigger starts selected. */
defaultSelected?: boolean;
/** Called when the trigger is selected or cleared. */
onSelectedChange?: (selected: boolean) => void;
/** The steps can be dragged about the board (and the trigger moved with the arrow keys). */
draggable?: boolean;
/** While on screen and untouched, a demo pointer plays with the steps and the chips. */
autoplay?: boolean;
/** Light or dark colours, or the reader's ('system'); without it, the page's color-scheme. */
colorScheme?: 'light' | 'dark' | 'system';
/** A menu open from the start (it closes as usual). Setting it turns the demo off. */
defaultMenu?: FlowchartMenu | null;
/** How far each step starts from its place, in px. Setting it turns the demo off. */
defaultOffsets?: Partial>;
className?: string;
}) {
const { ref: root, playing, take } = useAutoplay(8000);
const [conditions, setConditions] = useState(defaultConditions);
const [selected, setSelected] = useState(defaultSelected);
const [offsets, setOffsets] = useState(() => ({ ...ZERO, ...defaultOffsets }));
const [front, setFront] = useState('branch');
const [dragging, setDragging] = useState(false);
const [menu, setMenu] = useState