If you've ever needed to map out a process, explain a system, or document a decision tree, you know how painful it can be to draw and update flowcharts manually. Mermaid.js lets you create flowcharts using plain text, so your diagrams live right alongside your code and update without dragging a single box. A solid cheat sheet for Mermaid's flowchart syntax saves you from constantly hunting through docs and keeps your focus on the logic itself.

What Is Mermaid Flowchart Syntax?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from text written in a simple, Markdown-like language. For flowcharts specifically, you write a short block of text that describes nodes (shapes) and edges (connections between shapes), and Mermaid turns it into a visual diagram.

A flowchart in Mermaid starts with the flowchart keyword (or its older alias graph), followed by a direction and a series of node and link definitions. The entire diagram is rendered in SVG, which means it scales cleanly and works inside GitHub READMEs, documentation sites, wikis, and many online Mermaid editors.

How Do You Define Nodes in a Mermaid Flowchart?

Nodes are the building blocks of any flowchart. In Mermaid, you give each node an ID and optionally wrap it in different bracket types to change its shape. Here are the most common node shapes:

  • Default (rounded rectangle): A[Text]
  • Rectangle: A[Text] (same as default)
  • Rounded edges: A(Text)
  • Circle: A((Text))
  • Rhombus (diamond for decisions): A{Text}
  • Stadium / pill shape: A([Text])
  • Subroutine: A[[Text]]
  • Cylindrical (database): A[(Text)]
  • Hexagon: A{{Text}}
  • Parallelogram: A[/Text/]
  • Parallelogram (alt): A[\Text\]
  • Trapezoid: A[/Text\]
  • Trapezoid (alt): A[\Text/]
  • Double circle: A(((Text)))

A quick example:

flowchart TD
 Start((Start)) --> Input[/User Input/]
 Input --> Process[Process Data]
 Process --> Decision{Valid?}
 Decision -->|Yes| Output[Save Result]
 Decision -->|No| Input

How Do You Connect Nodes With Edges?

Edges define how one node links to another. The basic syntax uses dashes and arrows:

  • Arrow: A --> B
  • Open link (no arrow): A --- B
  • Link with text: A -->|Label| B or A -- Label --- B
  • Dotted link: A -.-> B
  • Dotted link with text: A -.->|Label| B
  • Thick link: A ==> B
  • Thick link with text: A ==>|Label| B
  • Invisible link (for layout control): A ~~~ B

You can also chain nodes in one line: A --> B --> C --> D.

How Do You Set the Flow Direction?

Mermaid supports four directions, set right after the flowchart keyword:

  • TD or TB top to bottom (most common)
  • BT bottom to top
  • LR left to right
  • RL right to left

For example, flowchart LR makes a left-to-right flowchart, which often fits better on wide screens.

Can You Group Nodes in Subgraphs?

Yes. Subgraphs let you cluster related nodes inside a labeled section. This is helpful for showing phases, modules, or swimlane-style groupings:

flowchart TD
 subgraph Phase1 [Phase 1: Data Collection]
 A[Survey] --> B[Raw Data]
 end
 subgraph Phase2 [Phase 2: Analysis]
 C[Clean Data] --> D[Report]
 end
 B --> C

Subgraphs support different directions too. You can set a subgraph to flow LR while the parent flows TD.

How Do You Add Styling to Flowchart Elements?

Mermaid gives you a few ways to style nodes inline:

  • style A fill:#f9f,stroke:#333,stroke-width:2px
  • classDef className fill:#e1f5fe,stroke:#0288d1 followed by class A className
  • style A,B,C fill:#lightgreen for applying styles to multiple nodes at once

These are useful for color-coding decision outcomes, highlighting warning states, or matching your team's brand colors.

What Are the Most Common Mistakes When Writing Mermaid Flowcharts?

Even though the syntax is simple, a few patterns trip people up repeatedly:

  1. Using special characters in labels without quotes. If your text contains parentheses, brackets, or other special characters, wrap the label in quotes: A["Text with (parentheses)"].
  2. Forgetting the semicolon for multiple links on one line. You can separate link statements with a semicolon, but many people forget this and get parse errors.
  3. Duplicate node IDs with different labels. Mermaid uses the ID to determine uniqueness. If you define A[First] and later A[Second], the second definition wins. Use distinct IDs for distinct nodes.
  4. Mixing graph and flowchart keywords. Both work, but flowchart supports features like subgraph direction that graph does not. Stick with flowchart for new diagrams.
  5. Not quoting pipe characters in labels. Pipes are used for edge labels, so A -->|"Yes | No"| B needs proper quoting to avoid parsing issues.

Quick Fix Tip

If your diagram fails to render, isolate the problem by commenting out nodes and edges one at a time until it works. Most errors come from a single malformed line.

What Does a Complete Mermaid Flowchart Look Like?

Here's a realistic example showing a user login flow with decisions, error handling, and subgraphs:

flowchart TD
 subgraph Input
 A[Enter Credentials]
 end

 subgraph Validation
 B{Valid Format?}
 C[Check Database]
 D{User Exists?}
 E{Password Correct?}
 end

 subgraph Output
 F[Dashboard]
 G[Show Error]
 H[Lock Account]
 end

 A --> B
 B -->|No| G
 B -->|Yes| C
 C --> D
 D -->|No| G
 D -->|Yes| E
 E -->|Yes| F
 E -->|No| G
 G -->|3 Failures| H
 G -->|Retry| A

 style F fill:#c8e6c9,stroke:#2e7d32
 style G fill:#ffcdd2,stroke:#c62828
 style H fill:#ffcdd2,stroke:#c62828
 classDef default fill:#e3f2fd,stroke:#1565c0

This pattern of Input → Validation → Output with error loops is common in real documentation and worth memorizing as a template.

Where Can You Practice and Preview Mermaid Flowcharts?

The fastest way to test your syntax is the official Mermaid Live Editor. It renders your diagram in real time as you type and gives you a shareable URL. Other good options include VS Code extensions, GitHub's built-in Mermaid rendering in Markdown, and various online diagram editor tools that support Mermaid.

How Do Mermaid Flowcharts Compare to Other Mermaid Diagram Types?

Flowcharts are just one diagram type in Mermaid. If you need to show object relationships, class diagrams use a different syntax focused on attributes and methods. For showing interactions between actors over time, sequence diagrams follow their own rules with participants and messages. Understanding which diagram type fits your use case prevents you from forcing flowchart syntax into problems it wasn't designed to solve.

Practical Flowchart Syntax Cheat Sheet

What You Need Syntax
Start a flowchartflowchart TD
Rectangle nodeA[Label]
Rounded nodeA(Label)
Diamond (decision)A{Label}
CircleA((Label))
Database shapeA[(Label)]
Arrow with labelA -->|text| B
Dotted arrowA -.-> B
Thick arrowA ==> B
Subgraphsubgraph id [Title] ... end
Apply stylestyle A fill:#color
Chain nodesA --> B --> C
Invisible linkA ~~~ B

Next Steps: Build Your First Flowchart Right Now

  1. Open the Mermaid Live Editor.
  2. Type flowchart TD and hit enter.
  3. Add a start node: Start((Begin)).
  4. Add two or three connected nodes using arrows.
  5. Add one diamond decision node with two labeled branches.
  6. Try changing TD to LR and see how layout shifts.
  7. Wrap a group of nodes in a subgraph with a label.
  8. Copy the syntax into a GitHub README to confirm it renders.

Keep this cheat sheet bookmarked. The more you write flowcharts in Mermaid, the less you'll need to look up syntax and the faster your documentation will come together.