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).

CodeDirection
graph TD / flowchart TDTop to bottom (same as TB)
graph LRLeft to right, good for pipelines and wide screens
graph BTBottom to top
graph RLRight to left
Rendering diagram…
Mermaid code
graph LR
  A[Write code] --> B[Review]
  B --> C[Merge]
  C --> D[Deploy]
The same steps in graph LR. Change LR to TD to stack them vertically.

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.

CodeShape
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
Rendering diagram…
Mermaid code
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 --> done

Subgraphs

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.

Rendering diagram…
Mermaid code
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.

CodeEffect
style A fill:#fef3c7,stroke:#d97706Style one node
classDef bad fill:#fee2e2,stroke:#ef4444Define a class
class A,B badApply a class to several nodes
A:::bad --> BApply a class inline
linkStyle 0 stroke:#ef4444Style the first link
Rendering diagram…
Mermaid code
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:#ef4444

Special 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.
Rendering diagram…
Mermaid code
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.

ProblemFix
A --> endA lowercase node called end closes a subgraph and breaks the chart. Write End or end_node.
A---oBA 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)"].
```mermaidA Markdown fence pasted with the code. Paste only the Mermaid source, or let the editor ignore the fence.
graph tdThe 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.