# Flow Diagram

> Steps and decisions joined by arrows, with the path taken lit.

```tsx
'use client';

import { useState } from 'react';
import { Button, FlowDiagram } from '@brand-studio/ui';
import type { FlowEdge, FlowNode } from '@brand-studio/ui';

const nodes: FlowNode[] = [
  { id: 'read', label: 'Read the ticket', tag: 'Agent' },
  { id: 'found', label: 'Order found?', kind: 'decision' },
  { id: 'window', label: 'Inside 30 days?', kind: 'decision' },
  { id: 'ask', label: 'Ask for the order number', tag: 'Agent' },
  { id: 'refund', label: 'Draft a refund', tag: 'Agent' },
  { id: 'credit', label: 'Offer store credit', tag: 'Agent' },
  { id: 'approve', label: 'Approve the reply', tag: 'You', note: 'Nothing is sent before this.' },
  { id: 'send', label: 'Send', tag: 'Agent' },
];
const edges: FlowEdge[] = [
  { from: 'read', to: 'found' },
  { from: 'found', to: 'window', label: 'Yes' },
  { from: 'found', to: 'ask', label: 'No' },
  { from: 'ask', to: 'read', label: 'Reply' },
  { from: 'window', to: 'refund', label: 'Yes' },
  { from: 'window', to: 'credit', label: 'No' },
  { from: 'refund', to: 'approve' },
  { from: 'credit', to: 'approve' },
  { from: 'approve', to: 'send' },
];
const tickets = [
  { name: 'Ticket 4812', path: ['read', 'found', 'window', 'refund', 'approve', 'send'] },
  { name: 'Ticket 4813', path: ['read', 'found', 'window', 'credit', 'approve', 'send'] },
  { name: 'Ticket 4814', path: ['read', 'found', 'ask'] },
];

export default function FlowDiagramDemo() {
  const [ticket, setTicket] = useState(0);
  return (
    <div style={{ width: '100%', maxWidth: 620, display: 'grid', gap: 16 }}>
      <div role="group" aria-label="Ticket" style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
        {tickets.map((item, index) => <Button key={item.name} tone={index === ticket ? 'primary' : 'secondary'} aria-pressed={index === ticket} onClick={() => setTicket(index)}>{item.name}</Button>)}
      </div>
      <FlowDiagram title="How a refund request is handled" nodes={nodes} edges={edges} lit={tickets[ticket].path} />
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, FlowDiagram } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { FlowDiagram } from '@brand-studio/ui';
```

```tsx
<FlowDiagram
  title="How a refund request is handled"
  nodes={[
    { id: 'read', label: 'Read the ticket', tag: 'Agent' },
    { id: 'found', label: 'Order found?', kind: 'decision' },
    { id: 'refund', label: 'Draft a refund', tag: 'Agent' },
    { id: 'ask', label: 'Ask for the order number', tag: 'Agent' },
  ]}
  edges={[
    { from: 'read', to: 'found' },
    { from: 'found', to: 'refund', label: 'Yes' },
    { from: 'found', to: 'ask', label: 'No' },
  ]}
  lit={['read', 'found', 'refund']}
/>
```

You give the nodes and the links between them; the component places them. A node sits one rank after the furthest step that leads to it, and a link that skips a rank gets a lane of its own so it never runs under a node. A link back to an earlier step is drawn dashed, against the flow.

## Direction

The diagram runs top to bottom on a narrow screen and turns left to right when every rank has room for a readable node. A short flow turns sooner than a long one.

```tsx
import { FlowDiagram } from '@brand-studio/ui';

export default function FlowDiagramAcrossDemo() {
  return (
    <div style={{ width: '100%' }}>
      <FlowDiagram
        title="Where an answer comes from"
        nodes={[
          { id: 'ask', label: 'Your question' },
          { id: 'notes', label: 'Search the notes', tag: 'Tool' },
          { id: 'orders', label: 'Look up the order', tag: 'Tool' },
          { id: 'answer', label: 'Write the answer', tag: 'Agent', note: 'Each claim cites its source.' },
        ]}
        edges={[{ from: 'ask', to: 'notes' }, { from: 'ask', to: 'orders' }, { from: 'notes', to: 'answer' }, { from: 'orders', to: 'answer' }]}
        lit={['ask', 'notes', 'answer']}
      />
    </div>
  );
}
```

## Nodes

- `kind: 'decision'` draws a pill for a question. Label the links that leave it.
- `tag` says who or what does the step, such as "Agent", "Tool" or "You".
- `note` adds a second line.

## The path taken

`lit` lists the ids of the nodes on one path. Those nodes and the links between them take the accent, which shows the route an agent took through its own rules.

## Accessibility

- The nodes are an ordered list in reading order, and each one says in words which steps come next, with the link's label.
- The arrows are decoration for screen readers and are drawn once the nodes have a size, so the steps read before JavaScript runs.
- A lit node has a heavier border as well as the accent, so the path does not depend on colour alone.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `title` | `string` | – |
| `nodes` | `FlowNode[]` | – |
| `edges` | `FlowEdge[]` | – |
| `lit?` | `string[]` | – |
| `nextLabel?` | `string` | `'Next'` |
| `hideTitle?` | `boolean` | `false` |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/flow-diagram/
