Diagram

For isolated previews, theme switching, and sandbox editing, open the Diagram playground on holydocs.com .

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.

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.

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

More

• Interactive playground: Diagram on holydocs.com
• Component library index: /components