If you've ever tried to explain a process to a teammate, document a system, or plan a project workflow using only text, you know how fast things get confusing. Mermaid flowcharts solve this by turning plain-text descriptions into visual diagrams. But to make them work, you need to know the syntax and that's exactly what this reference guide covers. Whether you're embedding diagrams in documentation, writing markdown files, or working inside tools like GitHub, GitLab, or Notion, understanding Mermaid flowchart syntax lets you create clear, version-controllable diagrams without dragging boxes around in a GUI.

What is Mermaid flowchart syntax?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from text-based code. The flowchart (or graph) diagram type is one of its most commonly used features. Instead of opening a drawing tool and manually placing shapes, you write short lines of code that describe nodes and the connections between them. Mermaid then generates a visual flowchart automatically.

The syntax uses keywords like graph or flowchart to start a diagram, followed by lines that define shapes, labels, and arrows. Here's a minimal example:

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

This creates a top-down flowchart with two boxes connected by an arrow. The TD sets the direction (top-down). You can also use LR for left-to-right, BT for bottom-to-top, or RL for right-to-left.

For a deeper look at foundational syntax rules, see our Mermaid flowchart syntax breakdown.

How do you define nodes and shapes?

Nodes are the building blocks of any Mermaid flowchart. Each node has an ID (a short reference name) and a shape determined by the brackets or characters you wrap around its label. Here are the most common shape definitions:

  • A[Text] Rectangle (standard process box)
  • A(Text) Rounded rectangle (often used for start/end)
  • A{Text} Diamond (decision point)
  • A((Text)) Circle
  • A>Text] Asymmetric/flag shape
  • A[[Text]] Subroutine shape (double-bordered rectangle)
  • A[(Text)] Cylinder (database symbol)
  • A[/Text/] Parallelogram (input/output)

When you choose shapes, think about what each box represents in your process. Diamonds are for yes/no decisions. Rectangles are for steps. Cylinders typically represent databases. Using shape conventions consistently makes your diagrams easier to read. If you're comparing these to standard notations, our guide on UML flowchart notation standards covers how these symbols align with industry norms.

How do you connect nodes with arrows?

Connections (also called links or edges) define the flow between nodes. Mermaid uses several arrow styles:

  • A --> B Arrow (A points to B)
  • A --- B Link without arrowhead
  • A -->|label| B Arrow with text label
  • A -.-> B Dotted arrow
  • A ==> B Thick/bold arrow
  • A -.->|label| B Dotted arrow with label
  • A ==>|label| B Thick arrow with label

Decision points are where labeled connections become important. A diamond node typically has two outgoing arrows one labeled "Yes" and another labeled "No" that route the flow to different paths.

What does a real-world flowchart look like?

Here's a practical example showing a user login process:

graph TD
  A([User visits login page]) --> B[/Enter credentials/]
  B --> C{Valid credentials?}
  C -->|Yes| D[Grant access]
  C -->|No| E[Show error message]
  E --> B
  D --> F((Dashboard))

This flowchart uses a parallelogram for input, a diamond for a decision, standard rectangles for processes, a circle for the final destination, and a rounded rectangle for the start. The arrow from the error message loops back to the input step, showing the retry flow.

If you're curious how Mermaid compares to other visual programming approaches, check out this comparison chart of flowchart syntax options.

How do you group related steps with subgraphs?

Complex processes often have clusters of related steps. Mermaid handles this with subgraphs, which draw a box around a group of nodes and give the group a label.

graph TD
  A[Submit form] --> subgraph validation[Validation]
    B[Check required fields]
    C[Validate email format]
  end
  validation --> D[Save to database]

Subgraphs are especially useful for showing phases in a process, grouping related functions, or separating frontend and backend logic in a system diagram.

What are the most common mistakes with Mermaid flowchart syntax?

Mermaid is straightforward, but a few errors come up again and again:

  • Using reserved keywords as node IDs. Words like end, subgraph, and graph can conflict with the parser. Avoid them or wrap labels carefully.
  • Forgetting the direction keyword. Every Mermaid flowchart starts with graph TD, graph LR, flowchart TD, or similar. Without it, nothing renders.
  • Mismatched brackets. If you open a node label with [, it needs a closing ]. Miss one and the whole diagram breaks.
  • Special characters inside labels. Characters like #, (, ), and { can confuse the parser if not handled with quotes or HTML entity workarounds. Wrap tricky labels in quotes: A["Label with (parentheses)"].
  • Overcrowding a single diagram. Huge flowcharts with 30+ nodes are hard to read even when the syntax is correct. Break them into smaller linked diagrams when possible.

How do you add styles and classes to flowchart nodes?

Mermaid supports basic styling directly in the syntax. You can apply inline styles or define reusable CSS-like classes:

graph TD
  A[Start] --> B[Process]
  style A fill:#4CAF50,color:#fff
  style B fill:#2196F3,color:#fff

For reusable styles across many nodes, define a class:

classDef success fill:#4CAF50,color:#fff
  class A success

This keeps your diagram clean and makes global color changes easy. Note that styling capabilities vary depending on where you render the diagram. GitHub's Mermaid renderer, for instance, supports basic styles, but some features may look different in other platforms.

Tips for writing clean, maintainable Mermaid flowcharts

  • Use short, descriptive node IDs. login_check is easier to maintain than n1.
  • Comment your code. Mermaid supports %% for comments. Use them to explain non-obvious logic.
  • Align your indentation. Though Mermaid doesn't require it for parsing, consistent indentation makes editing much easier.
  • Keep labels concise. Long text inside small shapes gets clipped in many renderers. Aim for 3–6 words per node.
  • Test rendering in your target platform. A diagram that looks perfect in the Mermaid Live Editor might render slightly differently inside a wiki or CI/CD tool.
  • Use the flowchart keyword over graph when possible. The newer flowchart keyword supports additional features like richer link syntax.

Quick reference checklist for your next Mermaid flowchart

  1. Start with graph TD or flowchart TD and pick your direction (TD, LR, BT, RL).
  2. Define every node with a unique ID and appropriate shape brackets.
  3. Connect nodes with arrows. Add labels to decision branches.
  4. Use subgraph to group related steps when the diagram grows.
  5. Escape or quote any special characters in labels.
  6. Apply styles for visual clarity color decisions differently from process steps.
  7. Test your diagram in the Mermaid Live Editor before committing to docs.
  8. Write %% comments for complex logic so future editors understand your intent.
  9. Split diagrams larger than ~20 nodes into smaller, linked diagrams.

Start with a simple diagram today even three boxes and two arrows. Once the basic syntax feels natural, you'll find that building larger flowcharts is just repeating the same patterns with more nodes and connections.