Diagram

Render a Mermaid diagram from a source string. For AI outputs that emit flowcharts / sequence / class diagrams — pipe the Markdown code-fence body straight in.

Installation

pnpm

pnpm dlx @hex-core/cli add diagram

Usage

tsx

import { Diagram } from "@/components/ui/diagram"

Inline flowchart

Static diagram from string source.

tsx

<Diagram>{`flowchart LR\n  A[User query] --> B[Retrieve]\n  B --> C[Generate]\n  C --> D[Respond]`}</Diagram>

Render mermaid blocks from streaming AI output

Extract code-fence body from agent output, pass to Diagram.

tsx

const blocks = extractMermaidBlocks(agentMessage);
{blocks.map((src, i) => (
  <Diagram key={i} id={`d-${i}`} theme="dark" onError={(e) => log(e)}>
    {src}
  </Diagram>
))}

API Reference

Prop	Type	Default	Description
`children`required	`string`	—	Mermaid source. Pass the raw text body of a ```mermaid``` code fence.
`theme`	`enum`	default	Mermaid color theme — one of "default" \| "dark" \| "forest" \| "neutral".
`id`	`string`	—	Stable ID for the rendered SVG. Required when multiple diagrams share a page; auto-generated when omitted.
`onError`	`function`	—	Called with the engine's error message on parse/render failure.
`className`	`string`	—	Additional CSS classes on the container.

AI Guidance

When to use

Render Mermaid diagrams emitted by AI agents in their responses (flowchart, sequence, class, ER, gitGraph, mindmap, timeline). Also good for static documentation diagrams in AI-app docs.

When not to use

Don't use for interactive node graphs (use `<Canvas>` with reactflow). Don't use for charts (use a charting lib). Don't use for static SVG icons (just render SVG directly).

Common mistakes

Forgetting to provide a stable `id` when rendering multiple diagrams on the same page — mermaid's internal cache keys collide and re-renders break
Passing untrusted user input as `children` — mermaid's strict mode protects against XSS in the SVG output, but malformed input can still trip the parser. Validate upstream
Re-creating the source string on every render — the effect re-renders the diagram on identity change, which is expensive for large diagrams. Memoize
Not handling onError — broken syntax silently shows nothing without the error fallback being read

Accessibility

Mermaid SVG output includes basic role='graphics-document' semantics, but lacks rich navigation. For agent diagram outputs, also expose a parallel text description (the original Mermaid source itself, in a <details> or aria-describedby) so screen-reader users get the structure.

Related components

Token budget: 380

Verified against @hex-core/components@1.12.0

Edit this page on GitHub