Mermaid Flowchart Syntax Reference Guide for Developers

If you work with diagrams in Markdown files, wikis, or documentation platforms, you've probably seen Mermaid diagrams rendered inline without any image files. Knowing the flowchart syntax well means you can sketch a process, decision tree, or system flow in seconds right inside your editor. This reference covers the Mermaid flowchart syntax developers actually use day to day, from basic nodes to styled subgraphs, with examples you can copy and adapt right now.

What Is Mermaid Flowchart Syntax and Why Do Developers Use It?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from plain text. You write simple markup, and Mermaid converts it into an SVG flowchart. No drag-and-drop editor. No exported images to maintain. The diagram lives as code in your repository, which means it gets versioned, reviewed, and updated alongside everything else.

Developers use Mermaid flowcharts because they remove friction from communicating workflows. Instead of opening a separate diagramming tool, screenshotting the result, pasting it into a doc, and repeating the process every time something changes, you update a few lines of text. GitHub, GitLab, Notion, Obsidian, and many other platforms render Mermaid syntax natively, so the diagrams appear wherever your documentation lives.

This approach falls under "diagram as code" the same philosophy behind tools like PlantUML. If you've worked with PlantUML flowchart syntax for system architecture, the mental model is similar: text in, diagram out.

How Do You Start a Mermaid Flowchart?

Every Mermaid flowchart begins with a graph declaration that sets the flow direction. You write the keyword graph followed by a direction code:

graph TD top to bottom (the most common layout)
graph LR left to right
graph RL right to left
graph BT bottom to top

After the opening line, you define nodes and the connections between them. Here's the simplest possible flowchart:

graph TD
A[Start] --> B[End]

This renders two boxes connected by an arrow. A and B are node IDs. The text inside the square brackets becomes the visible label. That's all it takes to get a working diagram.

What Node Shapes Can You Use in a Mermaid Flowchart?

Mermaid supports several node shapes by changing the bracket characters around your label text. These shapes carry semantic meaning rectangles for processes, diamonds for decisions, rounded edges for start/end states:

A[Text] Rectangle (standard process step)
A(Text) Rounded rectangle (start or end points)
A{Text} Diamond (decision or conditional)
A{{Text}} Hexagon (preparation or setup step)
A[(Text)] Cylinder (database or storage)
A((Text)) Circle (connector or reference point)
A>Text] Asymmetric/flag shape (manual operation)
A[/Text/] Parallelogram (input/output)
A[\Text\] Parallelogram alt (alternative input/output)
A[/Text\] Trapezoid
A[\Text/] Trapezoid alt

Using the right shape makes your diagram immediately readable to anyone familiar with flowchart conventions. A diamond tells viewers "a decision happens here" without needing extra explanation.

How Do You Connect Nodes with Different Arrow Types?

Connection syntax is where Mermaid really shines for quick diagramming. You chain node IDs together with arrow operators:

A --> B Solid arrow (direct flow)
A --- B Solid line without arrowhead (association)
A -.-> B Dotted arrow (indirect or conditional flow)
A ==> B Thick arrow (emphasis or important path)
A --text--> B Arrow with a label
A -.text.-> B Dotted arrow with label
A ==text==> B Thick arrow with label
A -->|text| B Arrow with label using pipe syntax

A practical decision flow might look like this:

graph TD
  A[/User Input/] --> B{Valid?}
  B -->|Yes| C[Process Data]
  B -->|No| D[Show Error]
  D --> A
  C --> E((Done))

This reads naturally: user input goes to a validation check, branches on the result, and the error path loops back. The arrow labels (|Yes| and |No|) make the logic obvious without side annotations.

How Do You Create Subgraphs to Group Related Nodes?

When a flowchart grows, you can group nodes into labeled sections using subgraph. This is useful for showing distinct systems, phases, or responsibility areas:

graph LR
  subgraph Authentication
    A[Login Page] --> B[Validate Credentials]
    B --> C{Two-Factor?}
  end
  subgraph Dashboard
    D[Load Data] --> E[Render Widgets]
  end
  C -->|Yes| F[2FA Prompt]
  C -->|No| D
  F --> D

Subgraphs draw a visible boundary around related nodes and display a title. You can also set the direction inside a subgraph independently for example, subgraph title [direction: LR].

How Do You Style Nodes and Apply CSS Classes?

Inline styles let you color specific nodes using the style keyword followed by the node ID and CSS properties:

style A fill:#f9f,stroke:#333,stroke-width:2px
style B fill:#bbf,stroke:#333,color:#fff

For reusable styling, define a classDef and apply it with class:

classDef success fill:#4CAF50,color:#fff,stroke:#388E3C
classDef error fill:#f44336,color:#fff,stroke:#d32f2f
class A,B success
class C error

This keeps your stylesheet logic separate from the diagram structure similar to how you'd manage CSS classes in HTML. If you've used JavaScript flowchart rendering libraries, you'll notice Mermaid handles styling with less setup.

When Should You Use Mermaid Over a Drag-and-Drop Diagram Tool?

Mermaid works best when:

Your diagram lives in documentation that changes frequently
You want diagrams version-controlled in Git alongside your code
You need to embed diagrams in Markdown files on GitHub, GitLab, or wiki platforms
You prefer typing over clicking and dragging shapes
Multiple team members need to edit diagrams without paying for separate licenses

A drag-and-drop tool like Lucidchart or Draw.io is better when you need pixel-level layout control, complex non-standard shapes, or presentations for non-technical audiences. Mermaid trades visual polish for speed and maintainability.

If you're building flowcharts programmatically, you might also explore generating flowcharts with Python code for cases where diagrams are created dynamically from data.

What Are the Most Common Mistakes in Mermaid Flowchart Syntax?

These errors trip up developers most often:

Missing the graph direction on line one. Writing just flowchart without a direction code (TD or LR) can cause rendering issues in some parsers. Always declare it explicitly.
Using reserved words as node labels without quotes. Words like end, graph, or subgraph inside labels can confuse the parser. Wrap them in quotes: A["end"].
Forgetting that node IDs are not the same as labels. You can reference a node by its ID after defining it once. Writing A[Label 1] and then A[Label 2] elsewhere won't create two nodes it will try to relabel the same node.
Overlapping arrow labels on dense diagrams. When many arrows converge on a node, long labels crowd together. Keep labels to one or two words.
Not escaping special characters in labels. Parentheses, pipes, and brackets inside labels break the parser. Use quotes: A["Step (v2) | config"].
Mixing connection styles inconsistently. Using solid, dotted, and thick arrows without a clear convention makes diagrams harder to read. Pick a convention and stick to it.

How Do You Handle Links and Click Events in Mermaid Flowcharts?

Mermaid supports interactive click events that link nodes to URLs or trigger JavaScript functions. This works well when diagrams are rendered in HTML contexts:

click A "https://example.com/docs" "Open docs"
click B callbackFunction "Tooltip text"

The click directive takes the node ID, a URL or function name, and an optional tooltip. Note that interactivity only works when the diagram is rendered in a live HTML environment not in static image exports.

What Does a Real-World Mermaid Flowchart Look Like?

Here's a complete example modeling a user authentication flow with error handling:

graph TD
  A[/Enter Credentials/] --> B{Fields Empty?}
  B -->|Yes| C[Show Validation Error]
  C --> A
  B -->|No| D[Send Auth Request]
  D --> E{Response OK?}
  E -->|200| F[Store Token]
  F --> G[Redirect to Dashboard]
  E -->|401| H[Show Invalid Credentials]
  E -->|500| I[Show Server Error]
  H --> A
  I --> J[Retry or Contact Support]

classDef input fill:#E3F2FD,stroke:#1565C0
classDef decision fill:#FFF9C4,stroke:#F9A825
classDef error fill:#FFEBEE,stroke:#C62828
classDef success fill:#E8F5E9,stroke:#2E7D32

class A input
class B,E decision
class C,H,I error
class G success

This diagram is self-documenting: the node shapes communicate purpose, the colors highlight outcome types, and arrow labels explain branching logic. Anyone reviewing the code can understand the authentication flow without running the application.

Quick Reference: Mermaid Flowchart Syntax Cheat Sheet

Keep these patterns on hand for everyday use:

graph TD or graph LR declare direction
A[Label] rectangle node
A{Label} diamond decision node
A(Label) rounded node
A[(Label)] database/cylinder node
A --> B solid arrow
A -.-> B dotted arrow
A ==> B thick arrow
A -->|label| B labeled arrow
subgraph Title ... end group nodes
style ID fill:#color inline style
classDef name props reusable style class
class ID1,ID2 className apply class to nodes
click ID "url" make node clickable

Practical checklist before you commit a Mermaid flowchart:

Confirm the graph direction declaration is on the first line.
Check that every node ID is unique and used consistently.
Verify all special characters in labels are inside quoted strings.
Test the diagram in your target renderer (GitHub, GitLab, docs site) to catch platform-specific quirks.
Apply meaningful node shapes so the diagram communicates structure at a glance.
Keep arrow labels short one to three words maximum.
Use subgraphs once you exceed 10–12 nodes to maintain readability.
Run the Mermaid Live Editor to preview before pushing to production docs.