Mermaid Flowchart Syntax Guide
Everything you need to write Mermaid flowcharts, from the first graph TD line to subgraphs and styling. Every example below is rendered live, and you can open any of them in the editor.
graph TD vs flowchart TD
A Mermaid flowchart starts with a keyword and a direction. graph TD and flowchart TD draw the same top-down layout. flowchart is the keyword used in the current Mermaid documentation; graph is the original alias and still works, so existing graph TD code does not need to change. Named shapes require Mermaid 11.3 or newer, rather than a particular keyword.
TD and TB both mean top to bottom. The other directions are BT (bottom to top), LR (left to right) and RL (right to left).
| Code | Direction |
|---|---|
graph TD / flowchart TD | Top to bottom (same as TB) |
graph LR | Left to right, good for pipelines and wide screens |
graph BT | Bottom to top |
graph RL | Right to left |
graph LR
A[Write code] --> B[Review]
B --> C[Merge]
C --> D[Deploy]Nodes and shapes
A node is an ID followed by a label in brackets. The ID is used in links; the brackets decide the shape. Once a node is declared, refer to it by ID alone.
| Code | Shape |
|---|---|
A[Text] | Rectangle (process step) |
A(Text) | Rounded rectangle |
A([Text]) | Stadium (start or end) |
A{Text} | Diamond (decision) |
A{{Text}} | Hexagon (preparation) |
A[(Text)] | Cylinder (database) |
A((Text)) | Circle |
A[[Text]] | Subroutine |
A[/Text/] | Parallelogram (input or output) |
A>Text] | Asymmetric flag |
A@{ shape: doc, label: "Text" } | Named shapes in flowchart syntax (Mermaid 11.3+), such as doc, cyl or diam |
flowchart TD
start([Start]) --> input[/Order form/]
input --> check{In stock?}
check -->|Yes| db[(Orders DB)]
check -->|No| wait{{Back-order}}
db --> invoice@{ shape: doc, label: "Invoice" }
wait --> done((End))
invoice --> doneArrows and links
Links connect node IDs. Add text with pipes or inline, chain several links on one line, and use & to connect many nodes at once.
| Code | Link |
|---|---|
A --> B | Arrow |
A --- B | Line without an arrow |
A -->|text| B | Arrow with a label (or A -- text --> B) |
A -.-> B | Dotted arrow |
A ==> B | Thick arrow |
A --o B / A --x B | Circle or cross at the end |
A <--> B | Arrows at both ends |
A ---> B | Longer link: extra dashes add rank distance |
A --> B --> C | Chain of links |
A & B --> C | Several nodes link to C |
graph TD
U[User] -->|request| API
API -.->|cache miss| DB[(Database)]
API ==> R[Response]
Logs & Metrics --> Monitor
API --- LogsSubgraphs
A subgraph draws a box around a group of nodes. Give it an ID and a title, close it with end, and link to it like a node. A direction line inside a subgraph requests a different layout.
If a subgraph’s nodes are linked to the outside, Mermaid may ignore its direction and inherit the parent direction. Link to the subgraph itself instead, as in the example, and check the rendered result.
flowchart LR
subgraph client [Browser]
direction TB
UI[Editor] --> Render[Mermaid renderer]
end
subgraph cloud [Server]
Static[Static files]
end
Static --> client
client --> Export[PNG / SVG / PDF]Styling nodes and links
style changes a single node. classDef defines a reusable class, which you apply with class or the ::: shorthand. linkStyle styles links by their order, starting at 0.
| Code | Effect |
|---|---|
style A fill:#fef3c7,stroke:#d97706 | Style one node |
classDef bad fill:#fee2e2,stroke:#ef4444 | Define a class |
class A,B bad | Apply a class to several nodes |
A:::bad --> B | Apply a class inline |
linkStyle 0 stroke:#ef4444 | Style the first link |
graph TD
A[Build] --> B{Tests pass?}
B -->|Yes| C[Deploy]
B -->|No| D[Fix]:::bad
D --> A
classDef bad fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
style C fill:#dcfce7,stroke:#16a34a
linkStyle 2 stroke:#ef4444Special characters, line breaks and comments
- Wrap labels that contain brackets, quotes or other punctuation in double quotes: A["Save (draft)"].
- Use <br> for a line break inside a label: A["First line<br>Second line"].
- Write a double quote inside a label as #quot;.
- Lines that start with %% are comments and are not drawn.
graph TD
%% Labels with punctuation need quotes
A["Upload file (max 10 MB)"] --> B["Scan<br>for viruses"]
B --> C["Show #quot;Done#quot;"]Errors that break flowcharts
For other diagram types, check the preview error and the Mermaid documentation for that type.
| Problem | Fix |
|---|---|
A --> end | A lowercase node called end closes a subgraph and breaks the chart. Write End or end_node. |
A---oB | A node ID starting with o or x right after a link becomes a circle or cross edge. Add a space or rename the node. |
A[Save (draft)] | Unquoted brackets inside a label. Use A["Save (draft)"]. |
```mermaid | A Markdown fence pasted with the code. Paste only the Mermaid source, or let the editor ignore the fence. |
graph td | The direction must be uppercase: graph TD. |
Frequently asked questions
Is graph TD the same as flowchart TD?
Yes, both draw a top-down flowchart. flowchart is the keyword in the current Mermaid documentation; graph remains supported. Named shapes require Mermaid 11.3 or newer with either keyword.
What does TD mean in Mermaid?
Top down. The chart flows from the top of the page to the bottom. TB means the same thing.
How do I make a decision node?
Use curly braces: B{Approved?}. Then label the outgoing links, for example B -->|Yes| C and B -->|No| D.
How do I change the direction of only part of the chart?
Put the nodes in a subgraph and add a direction line, such as direction LR, inside it. If its nodes are linked to the outside, the direction can be ignored; link to the subgraph instead and check the preview.