August 20, 2026

Mermaid syntax cheat sheet

Q: How do I add a line break inside a node label?

Use ` ` inside a quoted label: `A["First line Second line"]`. Mermaid renders the label as HTML, so the tag works even though the rest of the syntax is not HTML.

Q: Can I control the layout?

Only indirectly. Pick the direction (`TD`, `LR`, `BT`, `RL`), use longer arrows (`--->`) to push nodes further apart, and group related nodes into subgraphs. Mermaid computes the rest — there are no coordinates.

Mermaid has a large reference and a small subset that covers almost everything people draw. This page is that subset: shapes, arrows, grouping, colours, and one copy-paste example per diagram type. Every snippet below renders as-is — paste it into the editor to see it.

The shortest diagram that works

A flowchart needs one declaration line and one arrow. TD means top-down; use LR for left-to-right, which suits wide processes better.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Ship it]
  B -->|No| A

A three-node flowchart, top to bottom.

A, B and C are node ids — internal names, never drawn. The text in brackets is the label, and the bracket style is what picks the shape.

Node shapes

Shape is chosen by the delimiter pair around the label. These are the ones worth remembering:

Syntax	Shape	Usual meaning
`A[Text]`	Rectangle	A step or action
`A(Text)`	Rounded	A start or end point
`A([Text])`	Pill	A terminator
`A[[Text]]`	Subroutine	A call into another process
`A[(Text)]`	Cylinder	A database or store
`A((Text))`	Circle	A junction
`A{Text}`	Diamond	A decision
`A{{Text}}`	Hexagon	A preparation step
`A[/Text/]`	Parallelogram	Input or output
`A[/Text\]`	Trapezoid	A manual operation

Quote the label when it contains brackets, colons or quotes: A["Load (raw) data"]. Without quotes the parser sees your punctuation as syntax.

Arrows

Syntax	Result
`A --> B`	Arrow
`A --- B`	Line, no arrowhead
`A -.-> B`	Dotted arrow
`A ==> B`	Thick arrow
`A -->\|label\| B`	Arrow with a label on it
`A --> B --> C`	Chain, written on one line
`A --> B & C`	One source, two targets

Arrow length is meaningful too: --> is one rank, ---> pushes the target one rank further down. It is the simplest layout control mermaid gives you.

Grouping with subgraphs

A subgraph draws a labelled box around nodes. Subgraphs nest, and arrows may cross their borders freely.

flowchart LR
  subgraph api["API"]
    H[Handler] --> S[(Postgres)]
  end
  subgraph worker["Worker"]
    Q[Queue] --> W[Job]
  end
  H --> Q

Two services, each with its own store.

Colour and styling

style paints one node. classDef plus class paints a set of them, which is what you want past three or four nodes.

flowchart TD
  A[OK] --> B[Failed]
  style A fill:#16a34a,stroke:#333,color:#fff
  classDef bad fill:#dc2626,stroke:#333,color:#fff
  class B bad

Colours are part of the diagram source, so they survive export and travel with the file. Nothing here depends on a theme setting in the tool that renders it.

One example per diagram type

Sequence diagram

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: request
  API->>DB: query
  DB-->>API: rows
  API-->>User: response

Class diagram

classDiagram
  class Animal {
    +String name
    +move()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

State diagram

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Idle: stop
  Running --> [*]: finish

Entity relationship diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }

Gantt chart

gantt
  title Project
  dateFormat YYYY-MM-DD
  section Phase 1
  Task 1 :a1, 2026-01-01, 5d
  Task 2 :after a1, 5d

Where mermaid renders on its own

GitHub — a fenced ```mermaid block renders in issues, pull requests, comments and README files.
GitLab — the same fenced block, in issues, merge requests and the wiki.
Notion — a code block with the language set to Mermaid renders next to the source.
Obsidian — a fenced mermaid block renders in preview mode.
Docs sites — Docusaurus, MkDocs Material and VitePress all support mermaid blocks.

That is the real reason to keep diagrams as mermaid rather than as images: the diagram lives in the same text file as the thing it describes, and a code review can see what changed in it.

Try any snippet on this page

Paste it into the code tab and it renders instantly — or build the same diagram on the canvas and read the syntax back.

Frequently asked

How do I add a line break inside a node label?

Use <br> inside a quoted label: A["First line<br>Second line"]. Mermaid renders the label as HTML, so the tag works even though the rest of the syntax is not HTML.

Why does my label break the diagram?

Almost always an unquoted bracket, parenthesis, colon or quote inside the label. Wrap the whole label in double quotes and the parser stops treating your punctuation as syntax.

Can I control the layout?

Only indirectly. Pick the direction (TD, LR, BT, RL), use longer arrows (--->) to push nodes further apart, and group related nodes into subgraphs. Mermaid computes the rest — there are no coordinates.

Which mermaid version does this editor use?

Mermaid 11, the current major version, so everything documented for v10 and v11 syntax renders here.