Mermaid.js Quick Reference (2025)

Mermaid.js Quick Reference (2025) #

Last verified: 2025-09-02

Quick start #

  • Use a fenced block in Markdown.
flowchart TD
  A[Start] --> B{OK?}
  B -->|Yes| C[Ship]
  B -->|No| D[Fix]
  • Prefer frontmatter (diagram-local config) over directives when possible.
```mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#00ffb3"
    lineColor: "#222"
---
flowchart LR
  A --> B
```
  • Browser API (v10+):
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

Tip: For selective rendering, set startOnLoad: false and call await mermaid.run({ querySelector | nodes, suppressErrors }).

Syntax quickstart + common fails #

  • Minimal rules
    • First line must declare diagram type and is case-sensitive (e.g., flowchart TD, xychart, quadrantChart, block).
    • Per-diagram frontmatter (--- config: ... ---) must be at the very top of the code block.
    • Indentation matters for some diagrams (e.g., mindmap); prefer spaces.
  • Common fails
    • Parse error: missing/wrong diagram keyword on first line.
    • Frontmatter not at top or invalid YAML.
    • quadrantChart points must be in [0,1].
    • sankey rows must be CSV with 3 columns; quote labels containing commas.
    • Click callbacks/HTML labels require securityLevel: 'loose' (trusted content only).

Configuration & theming #

  • Frontmatter (per-diagram): see example above.
  • Directive (JSON-like, still supported; later directives override earlier ones):
%%{init: { "theme": "dark", "logLevel": 1, "flowchart": { "htmlLabels": true }}}%%
flowchart TD
  A[Themed] --> B[Diagram]
  • XYChart theming (frontmatter under themeVariables.xyChart):
```mermaid
---
config:
  theme: base
  themeVariables:
    xyChart:
      titleColor: '#ff4d4f'
---
xychart
  title "Styled"
  x-axis "Q" [Q1, Q2]
  y-axis "Y" 0 --> 100
  bar [10, 20]
```

Security:

  • securityLevel controls trust and click/script surfaces.
  • Default is strict (safe default). Use loose only for trusted content (enables callbacks/HTML labels).
  • Some keys cannot be changed by directives (secure array), e.g., securityLevel, startOnLoad, maxTextSize.

Common diagrams (minimal cheats) #

  • Flowchart
flowchart LR
  A[Rect] --> B(Rounded)
  B --> C{Decision}
  C -->|Yes| D((Circle))
  C -->|No| E[Alt]
  A o--o E
  D x--x E
  subgraph group
    D --> F[Inside]
  end

Tip: New shapes via attributes (v11):

flowchart RL
  A@{ shape: manual-input, label: "User Input" }
  B@{ shape: docs, label: "Docs" }
  A --> B
  • Block
block
  a b c
  • Sankey (stable in v11)

Tip: See syntax docs; now stable (no -beta suffix).

  • XY Chart
xychart
  title "Quarterly Revenue"
  x-axis "Quarter" [Q1, Q2, Q3, Q4]
  y-axis "Revenue" 0 --> 100
  bar [20, 40, 60, 80]
  • Quadrant Chart
quadrantChart
  title Reach vs Impact
  x-axis Low --> High
  y-axis Low --> High
  quadrant-1 "Quick Wins"
  quadrant-2 "Long Term"
  quadrant-3 "Fill-ins"
  quadrant-4 "Big Bets"
  A: [0.2, 0.8]
  B: [0.6, 0.3]
  • Mindmap
mindmap
  Root
    Work
      Plan
      Do
    Home
      Relax
  • GitGraph
gitGraph
  commit
  branch feature
  checkout feature
  commit
  checkout main
  merge feature
  • Sankey (CSV)
sankey
"A","B",10
"B","C",5
  • Architecture (beta): use architecture-beta (see docs) for cloud/topology diagrams.

Layout and look #

  • ELK layout engine and hand-drawn look:
%%{init: {"layout": "elk", "look": "handDrawn"}}%%
stateDiagram-v2
  direction LR
  A --> B
  state B { C --> D }

Sizing & responsiveness #

  • Prefer responsive sizing: set per-diagram useMaxWidth: true (BaseDiagramConfig).
import mermaid from 'mermaid';
mermaid.initialize({
  startOnLoad: true,
  flowchart: { useMaxWidth: true },
  sankey: { useMaxWidth: true }
});
  • Ensure container styles allow scaling:
.mermaid, .mermaid svg { max-width: 100%; height: auto; }

Validation & debugging #

  • Validate without rendering:
import mermaid from 'mermaid';
mermaid.parseError = (err) => console.error(err);
if (await mermaid.parse(diagramText)) {
  await mermaid.run();
}
  • Programmatic API (no auto-run):
<div id="graphDiv"></div>
<script type="module">
  import mermaid from 'mermaid';
  mermaid.initialize({ startOnLoad: false });
  const def = 'graph TB\na-->b';
  const el = document.querySelector('#graphDiv');
  const { svg, bindFunctions } = await mermaid.render('graphDiv', def);
  el.innerHTML = svg;
  bindFunctions?.(el); // enable callbacks (e.g., click) on inserted SVG
</script>
  • Detect diagram type:
import mermaid from 'mermaid';
const t = mermaid.detectType('sequenceDiagram\nA->>B: hi'); // 'sequence'

  • Determinism for snapshots/tests:

    • deterministicIds: true, deterministicIDSeed: 'seed' for stable IDs
    • For hand-drawn look, also set handDrawnSeed

  • Common issues

    • “Parse error”: ensure the first line declares the diagram type.
    • Frontmatter must start at the top of the mermaid block.
    • Pie: negative values are rejected.
    • Click callbacks require securityLevel: ’loose'.

Version notes #

  • v10+: mermaid.run added, mermaid.init deprecated.

  • v11.10.x: XYChart, Block, Sankey are stable (no -beta); multiple sanitization fixes for labels/icons/KaTeX.

  • v11.1+: Architecture diagram introduced as architecture-beta.

  • v10.3+: Sankey introduced (sankey with CSV rows).

References #