Mermaid cheat sheet: every diagram type's syntax on one page

Which Mermaid diagram types exist?

Fourteen that are stable in Mermaid 11, each with its own first-line keyword. Flowchart, sequence, class, state and ER cover software design; gantt, timeline, journey, quadrant, pie and xychart cover planning and data; mindmap, gitGraph and block cover the rest.

What is the syntax for each Mermaid diagram type?

One minimal snippet and one table per type. Every snippet below is complete and parses as written; copy it, then extend it with the rows from its table.

Flowchart — flowchart TD | LR | BT | RL

Nodes are declared by id plus a shape bracket; links are the arrow operators. graph is the older synonym for flowchart.

flowchart LR
  A[Start] --> B{Valid?}
  B -- yes --> C([Done])
  B -- no --> D[Fix it]
  D --> B

Node shapes

flowchart TD
  A[Rectangle]
  B(Rounded)
  C([Stadium])
  D[[Subroutine]]
  E[(Database)]
  F((Circle))
  G>Flag]
  H{Decision}
  I{{Hexagon}}
  J[/Parallelogram/]
  K[/Trapezoid\]
  L(((Double circle)))
  M@{ shape: doc, label: "Document (v11.3+)" }

Arrow and link types

Subgraphs, direction and styling

flowchart LR
  subgraph api [API tier]
    direction TB
    A[Gateway] --> B[Service]
  end
  B --> C[(DB)]

Sequence diagram — sequenceDiagram

Participants appear in declaration order; each message is A arrow B: text. Fragments (alt, loop, par…) close with end.

sequenceDiagram
  autonumber
  actor U as User
  participant S as Server
  U->>+S: POST /login
  alt valid
    S-->>-U: 200 OK
  else invalid
    S-->>U: 401
  end
  Note over U,S: session starts

Message arrows

Participants, notes and fragments

Class diagram — classDiagram

Classes are declared with class Name { members } or implicitly by a relationship. Visibility prefixes and the relationship operators follow UML; see the UML diagram types reference for what each arrow means.

classDiagram
  direction LR
  class Animal {
    <<abstract>>
    +String name
    +speak() String
  }
  class Dog
  Animal <|-- Dog
  Owner "1" o-- "*" Dog : keeps
  Dog ..> Food : eats
  note for Dog "Barks"

Relationships

Members and annotations

State diagram — stateDiagram-v2

[*] is both the initial and the final pseudostate depending on which side of the arrow it sits. Composite states nest with braces.

stateDiagram-v2
  direction LR
  [*] --> Idle
  Idle --> Running : start
  state Running {
    [*] --> Fast
    Fast --> Slow
  }
  Running --> Idle : stop
  Running --> [*] : fail
  note right of Idle : waits for input

Entity relationship diagram — erDiagram

Each relationship line is ENTITY cardinality--cardinality ENTITY : label. The cardinality marks are crow's foot: the symbol nearest each entity describes that entity's side. Full notation on ER diagram symbols.

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    int id PK
    string email UK "login"
  }
  ORDER {
    int id PK
    int customer_id FK
  }

Crow's foot codes

Gantt chart — gantt

Set dateFormat first; every task is name : tags, id, start, end-or-duration. Tasks can start after another task's id.

gantt
  title Release plan
  dateFormat YYYY-MM-DD
  axisFormat %b %d
  excludes weekends
  section Build
    Design   :done,   d1, 2026-10-01, 5d
    Develop  :active, d2, after d1, 10d
  section Ship
    QA       :crit,   q1, after d2, 4d
    Launch   :milestone, m1, after q1, 0d

Pie chart — pie

Labels in double quotes, a colon, then a positive number; slices are drawn clockwise in the order given. showData prints the values in the legend.

pie showData
  title Traffic by source
  "Organic" : 62
  "Direct"  : 23
  "Referral" : 15

Timeline — timeline

Periods are lines; events follow a colon and several events can share one period. Sections group periods. The complete reference, with styling and errors, is on Mermaid timeline syntaxChen notation for ER diagramsCrow's foot notationUML diagram typesMermaid cheat sheetData flow diagram symbolsBPMN symbolsClass diagram symbolsActivity diagram symbols.

timeline
  title History of Mermaid
  section Early
    2014 : First release
  section Growth
    2022 : v9 : timeline added
    2024 : v11

Mindmap — mindmap

Hierarchy comes from indentation alone. The root may take a shape; children may too. Icons and classes attach to the preceding node.

mindmap
  root((Launch))
    Marketing
      Blog post
      ::icon(fa fa-pen)
      Newsletter
    Product
      [Changelog]
      ((Demo))

Git graph — gitGraph

Statements run in order like git commands on a current branch. main exists implicitly; orientation is set with gitGraph LR:, TB: or BT: (v11+).

gitGraph
  commit id: "init"
  branch develop
  checkout develop
  commit id: "feature"
  checkout main
  merge develop tag: "v1.0"
  commit type: HIGHLIGHT

Quadrant chart — quadrantChart

Both axes run 0 → 1. Quadrants are numbered counter-clockwise from the top right: 1 top-right, 2 top-left, 3 bottom-left, 4 bottom-right.

quadrantChart
  title Effort vs impact
  x-axis Low effort --> High effort
  y-axis Low impact --> High impact
  quadrant-1 Plan carefully
  quadrant-2 Do first
  quadrant-3 Skip
  quadrant-4 Maybe later
  Cheat sheet: [0.25, 0.8]
  Rewrite: [0.85, 0.7]

User journey — journey

Each task is name: score: actors; the score is 1 (worst) to 5 (best) and draws the face. Actors are comma-separated and get a colour each.

journey
  title Buy a ticket
  section Search
    Open app: 5: Rider
    Find route: 3: Rider
  section Pay
    Enter card: 2: Rider
    Confirm: 4: Rider, System

XY chart — xychart-beta

Bar and line series share the axes. The x-axis is a category list or a numeric range; the y-axis is a numeric range or auto. Newer releases also accept the keyword xychart; xychart-beta works everywhere Mermaid 10.6+ runs.

xychart-beta
  title "Signups per month"
  x-axis [Jan, Feb, Mar, Apr]
  y-axis "Signups" 0 --> 400
  bar [120, 180, 260, 340]
  line [120, 180, 260, 340]

Block diagram — block-beta

Blocks fill a grid left to right; columns sets the width, space leaves a cell empty, block:id … end nests a grid, and flowchart-style shapes and arrows apply. Newer releases also accept the keyword block.

block-beta
  columns 3
  Client space DB[("Database")]
  block:api:3
    columns 2
    Gateway Service
  end
  Client --> Gateway
  Service --> DB

How do I set the theme and config in Mermaid?

Two ways: a YAML frontmatter block above the diagram (preferred since v10.5) or an %%{init: …}%% directive on the first line. Both override the site defaults set by mermaid.initialize(); frontmatter wins when both are present.

---
title: Checkout
config:
  theme: forest
  look: handDrawn
  layout: elk
---
flowchart LR
  A --> B

%%{init: {'theme': 'dark', 'flowchart': {'curve': 'linear'}}}%%
flowchart LR
  A --> B

What are the most common Mermaid errors and how do I fix them?

Nearly every parse error is one of: a wrong or misspelled keyword on line one, a reserved word used as a node id, an unquoted special character in a label, or a host that bundles an older Mermaid than the syntax you used.

When is Mermaid the wrong tool?

When the diagram outgrows the syntax: thirty-plus nodes, swimlanes with cross-lane edges, BPMN, architecture diagrams with tiers, or anyone who needs to edit it without learning the grammar. Mermaid is excellent in READMEs and wikis and painful as a drawing tool.

ChartCraft takes the other route: you describe the diagram in a sentence and it lays it out (ELK layout, orthogonal routing, swimlanes, BPMN, ER with crow's foot, C4-style architecture). The Mermaid alternative page compares the two honestly; the AI diagram generator is the place to try it. For Mermaid syntax that is not on this page — the full timeline grammar, for instance — see Mermaid timeline syntaxChen notation for ER diagramsCrow's foot notationUML diagram typesMermaid cheat sheetData flow diagram symbolsBPMN symbolsClass diagram symbolsActivity diagram symbols.

Related guides and generators