> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagram

Interactive node-and-edge diagrams powered by ReactFlow with pan, zoom, and minimap.

**Interactive playground** For isolated previews, theme switching, and sandbox editing, open [the Diagram playground on holydocs.com](https://holydocs.com/components/diagram).

## When to use

Use this component when page density, comparison, or spatial composition matters as much as the words themselves.

## Live Examples

Every example below renders the real component directly inside HolyDocs, followed by the exact MDX you can paste into a page.

### Auth Flow

Service-to-service authentication flow.

**Auth Flow**

**Client**
  **API Gateway**
  **Auth Service**
  **Session Store**
  **POST /login**
  **verify**
  **read / write**
  **JWT**

~~~mdx
<Diagram title="Auth Flow" height="auto" edgeType="smoothstep" background="dots" backgroundGap="20" animatedEdges>
  <Controls showInteractive />
  <Node id="client" label="Client" description="Browser session" x={24} y={108} type="muted" />
  <Node id="api" label="API Gateway" description="Routing + rate limits" x={244} y={96} type="primary" width={210} />
  <Node id="auth" label="Auth Service" description="Validate credentials" x={540} y={28} width={206} />
  <Node id="db" label="Session Store" description="Persist issued tokens" x={540} y={190} type="success" width={206} />
  <Edge from="client" to="api" label="POST /login" />
  <Edge from="api" to="auth" label="verify" type="smoothstep" />
  <Edge from="auth" to="db" label="read / write" type="step" />
  <Edge from="auth" to="api" label="JWT" color="#8b5cf6" />
</Diagram>
~~~

### Branching Pipeline

Custom node content, multiple handles, minimap, and layered backgrounds.

**Branching Pipeline**

**Review Queue**

  **Release Router**

Classifies each build and fans it into the release path that fits the risk profile.

  **Production**
  **Observability**

  **validated build**
  **ship**
  **monitor**

~~~mdx
<Diagram title="Branching Pipeline" height="auto" edgeType="step" minimap>
  <Background variant="lines" gap="30" />
  <Background variant="dots" gap="10" size="1.2" />
  <Controls showInteractive />
  <MiniMap pannable zoomable />

  <Node id="queue" label="Review Queue" description="Incoming deployment requests" x={16} y={132} type="warning" width={210} />

  <Node id="router" label="Release Router" x={286} y={114} type="primary" width={220}>
    <Handle type="target" position="left" id="incoming" />
    <Handle type="source" position="right" id="ship" />
    <Handle type="source" position="bottom" id="observe" />
    <p>Classifies each build and fans it into the release path that fits the risk profile.</p>
  </Node>

  <Node id="prod" label="Production" description="Promote and deploy" x={592} y={40} type="success" width={206} />
  <Node id="ops" label="Observability" description="Logs, traces, alerts" x={592} y={224} type="muted" width={206} />

  <Edge from="queue" to="router" targetHandle="incoming" label="validated build" />
  <Edge from="router" sourceHandle="ship" to="prod" label="ship" animated type="smoothstep" />
  <Edge from="router" sourceHandle="observe" to="ops" label="monitor" type="straight" />
</Diagram>
~~~

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `--` | Optional title above the diagram. |
| `height` | `string \| number` | `320` | Stage height. Accepts numbers in px, CSS lengths, or "auto" to size from the diagram content. |
| `layout` | `"auto" \| "manual" \| "vertical" \| "horizontal"` | `"auto"` | Automatically stacks long linear flows; use "manual" to preserve every `x` and `y` exactly. |
| `backgroundId` | `string` | `"diagram-bg-0"` | React Flow background id. Useful when layering multiple `<Background />` children. |
| `background` | `"dots" \| "lines" \| "cross" \| "none"` | `"dots"` | Default React Flow background pattern when no  child is provided. |
| `backgroundVariant` | `"dots" \| "lines" \| "cross"` | `--` | Alias for `background` when you prefer React Flow's prop naming. |
| `backgroundGap` | `number \| [number, number]` | `20` | Gap between background marks. Use a comma-separated tuple such as `"16, 24"` for x/y gaps. |
| `backgroundSize` | `number` | `--` | Dot radius or cross rectangle size. |
| `backgroundOffset` | `number \| [number, number]` | `0` | Pattern offset. Use a comma-separated tuple such as `"4, 8"` for x/y offsets. |
| `backgroundColor` | `string` | `--` | Pattern color. |
| `backgroundBgColor` | `string` | `--` | Background fill color. |
| `backgroundClassName` | `string` | `--` | Class applied to the React Flow background container. |
| `backgroundPatternClassName` | `string` | `--` | Class applied to the generated background pattern. |
| `backgroundLineWidth` | `number` | `1` | Stroke thickness for the background pattern. |
| `controls` | `boolean` | `true` | Shows viewport controls by default. |
| `minimap` | `boolean` | `false` | Enables a miniature overview map. |
| `animatedEdges` | `boolean` | `false` | Animates every edge unless overridden per edge. |
| `edgeType` | `string` | `smoothstep` | Default built-in edge type for the flow. |

## Usage

Start from this baseline shape and then tailor the copy, data, or nesting to the page you are writing.

~~~mdx
<Diagram title="Auth Flow" height="auto" edgeType="smoothstep" background="dots" backgroundGap="20" animatedEdges>
  <Controls showInteractive />
  <Node id="client" label="Client" description="Browser session" x={24} y={108} type="muted" />
  <Node id="api" label="API Gateway" description="Routing + rate limits" x={244} y={96} type="primary" width={210} />
  <Node id="auth" label="Auth Service" description="Validate credentials" x={540} y={28} width={206} />
  <Node id="db" label="Session Store" description="Persist issued tokens" x={540} y={190} type="success" width={206} />
  <Edge from="client" to="api" label="POST /login" />
  <Edge from="api" to="auth" label="verify" type="smoothstep" />
  <Edge from="auth" to="db" label="read / write" type="step" />
  <Edge from="auth" to="api" label="JWT" color="#8b5cf6" />
</Diagram>
~~~

## Tips

- Layout components amplify good content and bad content equally. Fix hierarchy and copy length before adding more structure.
- Test long headings, narrow screens, and translated strings. Layout bugs usually appear at the edges, not in the happy path.
- Use layout to create contrast between sections, not to decorate every paragraph.

## Related Components

**[Columns](/components/columns)**

Equal-width column grid for side-by-side comparisons, feature lists, or mixed content layouts.
**[View](/components/view)**

Switchable content panels for presenting alternative configurations, languages, or frameworks.
**[Panel](/components/panel)**

Place supplementary content in the right-side panel alongside your main documentation.

## More

- Interactive playground: [Diagram on holydocs.com](https://holydocs.com/components/diagram)
- Component library index: [/components](/components)