Mermaid Reference

June 18, 2026 · View on GitHub

Short hints for generating Mermaid diagrams that render correctly in draw.io. draw.io's Mermaid parser covers 28 diagram types — the header keyword on the first non-directive line selects the type.

Canonical list & dialog/ELK docs: https://github.com/jgraph/drawio/discussions/5643.

General rules

  • Pick the type keyword carefully. graph/flowchart, classDiagram, stateDiagram-v2, erDiagram, sequenceDiagram, gitGraph, journey, pie, gantt, mindmap, timeline, quadrantChart, requirementDiagram, sankey-beta, xychart-beta, block-beta, c4Context/C4Container/C4Component, architecture-beta, radar-beta, packet-beta, venn-beta, treemap-beta, treeView-beta, ishikawa-beta, kanban, zenuml, wardley-beta, eventmodeling. Misspelling the header yields a blank diagram.
  • No trailing punctuation on node IDs. IDs are identifiers (myNode, node_1, A) — spaces, hyphens (in some contexts), and reserved words (end, class, subgraph) break the parse. Put display text in brackets or quotes instead: A["User's Account"].
  • One statement per line. Separate statements with newlines; ; works as a delimiter in flowchart but not everywhere.
  • Quote labels with special characters (:, -, parentheses, non-ASCII). Use " not '.
  • HTML in labels: only <br>, <b>, <i>, <u> are reliable across types. Use # for hex colors in styles, never rgb().
  • Diagrams can take a title block for some types: 
    ---
title: My Diagram
---
flowchart TD
  • Match the language of labels to the user's language — if the user writes in German, French, etc., the diagram labels should be in that language too.

Flowchart (most common)

flowchart TD
  A[Start] --> B{Decision?}
  B -->|Yes| C[Do thing]
  B -->|No| D[Skip]
  C --> E((End))
  D --> E
  • Direction: TD/TB (top-down), BT, LR, RL.
  • Node shapes by bracket: [rect], (rounded), ([stadium]), [[subroutine]], [(cylinder)], ((circle)), {rhombus}, {{hexagon}}, [/parallelogram/], [\parallelogram alt\], [/trapezoid\], >asymmetric].
  • Edges: --> arrow, --- no arrow, -.-> dotted, ==> thick, <--> bidirectional. Inline label: A -- text --> B or A -->|text| B.
  • Subgraphs: 
    subgraph Frontend
  A --> B
end

Styling & colors

Three ways — pick one, don't mix for the same node:

1. Inline per-node (style):

flowchart LR
  A[Start] --> B[End]
  style A fill:#f9f,stroke:#333,stroke-width:2px,color:#fff
  style B fill:#bbf,stroke:#f66,stroke-dasharray:5 5

2. Reusable classes (classDef + :::):

flowchart LR
  A:::happy --> B:::sad
  classDef happy fill:#dfd,stroke:#0a0
  classDef sad fill:#fdd,stroke:#a00

Or apply to many: class A,B,C happy.

3. Link styling (edges):

linkStyle 0 stroke:#f00,stroke-width:3px
linkStyle default stroke:#999

0 = first edge in order defined; default targets unstyled edges.

Style properties that work: fill, stroke, stroke-width, stroke-dasharray, color (font color).

Sequence diagram

sequenceDiagram
  participant U as User
  participant S as Server
  U->>S: Request
  S-->>U: Response
  Note right of S: Logged
  • Arrows: -> (no head), ->> (arrow), -->> (dashed), -x (X end), --x (dashed X).
  • Activate/deactivate: activate S / deactivate S or S->>+S2: call / S2-->>-S: return.
  • Blocks: alt/else/end, opt/end, loop/end, par/and/end, critical/option/end.
  • Notes: Note left of A, Note over A,B: text.
  • Optional autonumber after header numbers the messages.

Class diagram

classDiagram
  class Animal {
    +String name
    +int age
    +eat() void
  }
  class Dog
  Animal <|-- Dog : inherits
  Dog "1" --> "*" Bone : has
  • Relations: <|-- inherit, *-- composition, o-- aggregation, --> association, ..> dependency, ..|> realize, <--> bidirectional.
  • Visibility: + public, - private, # protected, ~ package.
  • Annotations: <<interface>>, <<abstract>>, <<enumeration>> inside the class block or via Animal <<interface>>.
  • Cardinality: quoted strings flanking the arrow ("1", "0..*", "*").

State diagram

stateDiagram-v2
  [*] --> Idle
  Idle --> Running : start
  Running --> Idle : stop
  Running --> [*]
  state Running {
    [*] --> Working
    Working --> Waiting : block
    Waiting --> Working : unblock
  }
  • Use stateDiagram-v2, not stateDiagram (v1 is legacy).
  • [*] = start (source) or end (target) depending on direction.
  • state X { ... } nests a compound state; state fork1 <<fork>>, <<join>>, <<choice>> mark junction nodes.
  • Transition labels: A --> B : event [guard] / action.

ER diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  CUSTOMER {
    string name
    string email PK
  }
  • Cardinality symbols: |o zero-or-one, || exactly-one, }o zero-or-many, }| one-or-many. Mirror on both sides (e.g., ||--o{).
  • Attribute blocks list type name [PK|FK|UK] plus optional comment in quotes.
  • Entity names are typically UPPERCASE by convention.

Journey

journey
  title Morning routine
  section Wake up
    Coffee: 5: Me
    Read news: 3: Me
  section Commute
    Drive: 2: Me, Traffic

Each task: Name: score(1-5): Actor[, Actor...]. Section headers group tasks.

Pie

pie showData title Browser share
  "Chrome" : 60
  "Firefox" : 20
  "Safari" : 20

showData is optional (renders the numbers). Quotes on labels, colon, numeric value.

Gantt

gantt
  title Project timeline
  dateFormat YYYY-MM-DD
  section Phase 1
  Design : a1, 2025-01-01, 7d
  Build  : after a1, 14d
  section Phase 2
  Test   : 2025-01-25, 5d
  • dateFormat is mandatory.
  • Task line: Name : [id,] [after id | YYYY-MM-DD], duration[d/w].
  • Status tags: done, active, crit before the id (crit a1).

Gitgraph

gitGraph
  commit
  branch develop
  checkout develop
  commit
  commit
  checkout main
  merge develop

Commands: commit [id: "x"] [tag: "v1"], branch name, checkout name, merge name, cherry-pick id: "x".

Mindmap

mindmap
  root((Project))
    Frontend
      React
      CSS
    Backend
      Node
      DB
  • Indentation (2-space increments) defines hierarchy.
  • Root shape: ((circle)), [rect], (rounded), ))cloud((, )hexagon(, {{hexagon}}.
  • No edges — they are implied by nesting.

Timeline

timeline
  title Company history
  section 2020s
    2021 : Founded
    2022 : Series A
         : Launched product
  section 2030s
    2030 : IPO

Colon separates year/label; multiple : lines under one year add sub-events.

Quadrant chart

quadrantChart
  title Reach vs Engagement
  x-axis Low --> High
  y-axis Low --> High
  quadrant-1 Stars
  quadrant-2 Question Marks
  quadrant-3 Dogs
  quadrant-4 Cash Cows
  Campaign A: [0.3, 0.6]
  Campaign B: [0.75, 0.85]

Point coords are [0..1, 0..1].

Requirement diagram

requirementDiagram
  requirement req1 {
    id: "1"
    text: "The system shall..."
    risk: high
    verifymethod: test
  }
  element user_story {
    type: "story"
  }
  user_story - satisfies -> req1

Requirement types: requirement, functionalRequirement, performanceRequirement, interfaceRequirement, physicalRequirement, designConstraint. Relations: contains, copies, derives, satisfies, verifies, refines, traces.

Sankey

sankey-beta
Source,Intermediate,10
Source,Direct,5
Intermediate,Sink,10

CSV-style: source,target,value. No header. No title (use frontmatter).

XY chart

xychart-beta
  title "Revenue"
  x-axis [jan, feb, mar, apr]
  y-axis "USD" 0 --> 10000
  bar [2500, 5000, 7500, 9000]
  line [3000, 4500, 6500, 8500]

bar [...] and line [...] can stack; order matters (later overlays earlier).

Block

block-beta
  columns 3
  A B C
  D["Wide"]:2 E
  A --> D

columns N sets grid width. Name:N spans N columns. Edges use flowchart arrow syntax.

C4

C4Context
  Person(user, "User")
  System(app, "App", "Does things")
  Rel(user, app, "Uses")
  • Variants: C4Context, C4Container, C4Component, C4Dynamic, C4Deployment.
  • Element helpers: Person, System, System_Ext, Container, ComponentDb, Boundary(id, "label", "type"), etc. Arguments are positional: (id, label, [type/tech], [description]).
  • UpdateElementStyle(tag, $bgColor="#…") and AddElementTag tweak appearance.

Architecture

architecture-beta
  group cloud(cloud)[Cloud]
  service api(server)[API] in cloud
  service db(database)[DB] in cloud
  api:R --> L:db
  • Built-in icons: cloud, server, database, disk, internet. Suffix edge ends with :T, :B, :L, :R to pick the side.
  • group id(icon)[Label] then in groupId on services places nodes.

Radar

radar-beta
  title Skills
  axis js["JS"], py["Python"], go["Go"]
  curve alice["Alice"]{80, 60, 70}
  curve bob["Bob"]{50, 90, 65}

Axes and curves are positionally aligned — list values in axis order, 0–100.

Packet

packet-beta
  0-15: "Source Port"
  16-31: "Dest Port"
  32-63: "Seq Number"

start-end (bit ranges) or single-bit N. Use a title frontmatter.

Venn

venn-beta
  set A ["Set A"]
  set B ["Set B"]
  union A,B
  text A ["only A"]
  text A,B ["shared"]

Define every union combination whose region you plan to label. text A,B [...] places text in intersections.

Treemap

treemap-beta
"Category"
    "Leaf 1": 40
    "Leaf 2": 60

Numbers are values (area-weighted). Indent (2+ spaces) for hierarchy.

Tree view

treeView-beta
  "Root"
    "Child 1"
      "Grandchild"
    "Child 2"

Pure indentation hierarchy, no numbers.

Ishikawa (fishbone)

ishikawa-beta
  Main Problem
    Category
      Cause
      Sub-cause
    Another Category
      Cause

First line after header is the problem; top-level indents are categories (Materials, Methods, Machinery, etc. — use whatever makes sense).

Kanban

kanban
  todo[To Do]
    task1[Write spec]@{ assigned: "Alice", priority: "High" }
  doing[In progress]
    task2[Build feature]
  done[Done]

Columns are id[Label] at indent 0; cards are id[Label]@{ metadata } inside. Metadata keys: assigned, priority (Very Low/Low/Medium/High/Very High), ticket.

ZenUML

zenuml
  @Actor User
  @Boundary Web
  @Control Service
  User -> Web: request
  Web -> Service: process()
  Service -> Web: result

Participant roles: @Actor, @Boundary, @Control, @Entity, @Database. Messages use -> with a colon-separated label. Supports if/else, while, par blocks like sequence diagrams.

Wardley map

wardley-beta
  title Tea Shop
  anchor Business [0.95, 0.63]
  component Cup of Tea [0.79, 0.61]
  component Kettle [0.43, 0.35] (inertia)
  Business -> Cup of Tea
  Cup of Tea -> Kettle
  evolve Kettle 0.62
  • Header wardley or wardley-beta; title optional.
  • anchor/component Name [visibility, evolution] — coords are [0..1, 0..1] (y = value-chain visibility, x = evolution from Genesis to Commodity).
  • Component evolution markers in parens: (inertia), (build), (buy), (outsource), (market).
  • Links: A -> B dependency, A +> B flow. evolve Name <x> adds an evolution target; evolution Genesis -> Custom -> Product -> Commodity relabels the x-axis stages.
  • Extras: note "text" [x,y], annotation N,[x,y] "text", accelerator/deaccelerator "text" [x,y].

Event Modeling

eventmodeling
  tf 01 ui CartUI
  tf 02 cmd AddItem
  tf 03 evt ItemAdded
  tf 04 rmo Cart
  • Each tf <id> <type> <Name> is a time-frame (column). Types: ui / pcr (processor), cmd / command, rmo / readmodel, evt / event — placed on the UI/Automation, Command/Read-Model, and Events swimlanes.
  • Wire frames with ->>: tf 04 evt ItemChanged ->> 02 ->> 03 links frame 04 back to 02 and 03.
  • Namespace.Name groups frames into slices (e.g. Order.ChangeOrder).
  • data <id> { ... } blocks attach payloads, referenced inline with [[id]]: tf 02 cmd AddItem [[AddItem01]].

When to prefer XML over Mermaid

  • Precise positions / custom coordinates.
  • draw.io-native shapes (AWS, Azure, GCP, P&ID, Cisco, electrical).
  • Mixed shape libraries or complex multi-layer diagrams.
  • Anything that needs exact colors per element with many variations — Mermaid's styling works but at scale XML is easier to reason about.

Default to Mermaid for the standard types above; reach for XML only when Mermaid's syntax clearly can't express what's needed.