Mermaid Flowchart Syntax: Nodes, Arrows, Shapes, and Subgraphs

Q: What is the difference between `graph` and `flowchart`?

`graph TD` is the original keyword and still renders. `flowchart TD` is the current grammar and is the only one that gets new features such as `@{ shape }` definitions and markdown labels. Use `flowchart` for anything new.

Q: How do I control spacing between nodes?

Mermaid exposes `nodeSpacing` and `rankSpacing` in its config, but not as part of the diagram text. MermanDraw adds a Layout panel in the editor so you can drag two sliders and see the result live, then export the SVG or PNG with that spacing baked in.

Q: Can I make a node a link?

Yes: `click A "https://example.com" "Tooltip"`. GitHub strips click handlers for security, so links only work in environments where you control the renderer.

Example

flowchart TD
    A[User] -->|Paste Mermaid code| B(MermanDraw)
    B --> C{Render}
    C -->|Beautiful| D[Diagram]
    C -->|Share| E[Link]
    E -->|Viral| A

Open in editor → Cheatsheet →

Syntax

Direction

flowchart LR
    A --> B --> C

TD/TB (top-down), LR (left-right), BT, and RL. LR usually fits wide screens and README columns better than TD once a diagram has more than five or six ranks.

Try this snippet →

Node shapes

flowchart TD
    A[Rectangle]
    B(Rounded)
    C([Stadium])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G{Decision}
    H{{Hexagon}}
    I[/Parallelogram/]
    J[\Trapezoid/]

Mermaid 11 adds a general form: K@{ shape: cyl, label: "Queue" } with dozens of named shapes (doc, cyl, hex, delay, and more).

Try this snippet →

Arrows and edge labels

flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -->|label| F
    F -- text --> G
    G --o H
    H --x I

Solid, open, dotted, and thick links; circle and cross endings. |label| after the arrow and -- text --> are equivalent ways to label an edge.

Try this snippet →

Subgraphs

flowchart TB
    subgraph Client
        UI --> State
    end
    subgraph Server
        API --> DB[(Postgres)]
    end
    State --> API

Subgraphs group nodes with a labelled box. Give a subgraph an ID and a title with subgraph id [Title] when you need to connect to the group itself.

Try this snippet →

Styling

flowchart LR
    A[Start] --> B[Done]
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
    class B ok
    style A stroke-width:2px

Inline style for one node, classDef + class for many. In MermanDraw you rarely need this: the theme picker restyles every node at once.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

Parentheses, brackets, or quotes inside a label: A[Click (here)] fails because ( opens a new shape.

Fix: Quote the label: A["Click (here)"]. Quoted labels accept any character, including #, ;, and markdown.
Using end as a node ID (start --> end). end closes subgraphs and is reserved.

Fix: Rename it (finish, done) or capitalise it (End). Also avoid graph, subgraph, style, and click as IDs.
Single-dash arrows (A -> B). That is sequence-diagram syntax; flowcharts need two dashes.

Fix: Use -->. AI models mix these up when they have just produced a sequence diagram in the same conversation.
Literal \n inside a label to force a line break.

Fix: Use <br/>: A["Line one<br/>Line two"]. Mermaid treats labels as HTML-ish text, not as escaped strings.
Linking two labelled nodes with the label repeated each time (A[User] --> B[API] and later A[User] --> C[DB]).

Fix: That works but is noisy. Declare each node once, then connect by ID: A --> C. If the label text differs between declarations, the last one wins.

Real-world examples

Complete, copy-ready flowcharts for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

What is the difference between `graph` and `flowchart`?

graph TD is the original keyword and still renders. flowchart TD is the current grammar and is the only one that gets new features such as @{ shape } definitions and markdown labels. Use flowchart for anything new.

How do I control spacing between nodes?

Mermaid exposes nodeSpacing and rankSpacing in its config, but not as part of the diagram text. MermanDraw adds a Layout panel in the editor so you can drag two sliders and see the result live, then export the SVG or PNG with that spacing baked in.

Can I make a node a link?

Yes: click A "https://example.com" "Tooltip". GitHub strips click handlers for security, so links only work in environments where you control the renderer.