Mermaid Flowchart Syntax Examples and Code Templates

If you've ever needed to explain a process, map out a system, or document a workflow without fiddling with drag-and-drop diagram tools, mermaid flowchart code examples are exactly what you need. Mermaid lets you create flowcharts using plain text syntax no design software, no mouse clicks, no formatting headaches. You write code, and it renders into a clean diagram. This matters because it means your flowcharts live right next to your documentation, version in Git, and stay editable by anyone who can read text.

What Exactly Is Mermaid Flowchart Code?

Mermaid is a JavaScript-based diagramming tool that takes a simple text-based syntax and converts it into visual diagrams in the browser. When people search for mermaid flowchart code examples, they're usually looking for the specific syntax needed to render a flowchart a diagram that shows steps, decisions, and the flow between them.

Think of it as writing a recipe in shorthand. Instead of drawing boxes and arrows manually, you declare your nodes and connections in text. The Mermaid library handles the layout and rendering for you. You can embed these diagrams in GitHub READMEs, documentation sites, wikis, and markdown-based tools.

How Do You Write a Basic Mermaid Flowchart?

Every Mermaid flowchart starts with the flowchart keyword (or the older graph keyword). After that, you define nodes and link them with arrows. Here's a simple example:

flowchart TD A[Start] --> B[Do something] B --> C[End]

This creates three nodes flowing top-down (TD). A, B, and C are node IDs. The text inside the brackets is what gets displayed. The --> arrows show the direction.

You can also change direction with LR (left to right), RL, or BT (bottom to top). For example:

flowchart LR A[Login] --> B[Dashboard] B --> C[Logout]

If you're working in markdown files, you might find it helpful to check out how to write flowchart diagram code in markdown for setup details.

What Are the Different Node Shapes You Can Use?

One of the strengths of Mermaid flowchart syntax is the variety of node shapes you can declare just by changing the bracket type. Here are the most used ones:

A[Text] Rectangle (standard process step)
A(Text) Rounded rectangle (start/end terminals)
A{Text} Diamond (decision point)
A([Text]) Stadium or pill shape
A[[Text]] Subroutine shape
A[(Text)] Cylinder (database)
A((Text)) Circle
A>Text] Flag or asymmetric shape
A{{Text}} Hexagon

Each shape carries a visual meaning. Diamonds signal decisions. Rectangles signal processes. Databases are cylinders. Using the right shape makes your flowchart readable without explanation. For a full breakdown of what each symbol represents, see flowchart symbols and their meanings.

How Do You Build a Flowchart With Decisions and Branches?

Most real-world flowcharts include decision points places where the path splits based on a condition. In Mermaid, you use the diamond shape {} for decisions and label each branch:

flowchart TD A[Place Order] --> B{In Stock?} B -->|Yes| C[Ship Item] B -->|No| D[Notify Customer] C --> E[Complete] D --> E

The pipe syntax |Yes| and |No| adds labels to the arrows. This makes it clear which condition leads where. You can also link multiple nodes to a single node (like E above) to show paths converging.

Here's a slightly more complex example a user authentication flow:

flowchart TD A[Open App] --> B[Enter Credentials] B --> C{Valid?} C -->|Yes| D[Load Dashboard] C -->|No| E[Show Error] E --> B D --> F{Has Notifications?} F -->|Yes| G[Show Alert] F -->|No| H[Show Home]

Notice how E --> B loops the user back to the credentials step. This kind of loop is easy to express in code but annoying to draw manually.

How Do You Connect Nodes in Non-Linear Ways?

Mermaid supports several arrow and link types beyond the basic -->:

A --> B Arrow with no label
A -->|Label| B Arrow with label
A --- B Line without arrowhead
A -.- B Dotted line, no arrow
A -.-> B Dotted line with arrow
A ==> B Thick arrow
A ==>|Label| B Thick arrow with label

You can also create subgraphs to group related nodes:

flowchart TD subgraph Auth["Authentication"] A[Login] --> B{Valid?} B -->|Yes| C[Token] end subgraph App["Application"] D[Dashboard] --> E[Settings] end C --> D

Subgraphs are useful for visually separating modules, phases, or systems within a larger diagram.

What Are Common Mistakes When Writing Mermaid Flowchart Code?

Even though the syntax is straightforward, there are a few things that trip people up:

Forgetting the direction keyword. You need flowchart TD or flowchart LR at the top. Without it, the parser throws an error.
Using special characters in node text. Characters like #, ;, &, and " inside labels can break rendering. Wrap problematic text in quotes: A["Order #123"].
Mismatched brackets. Every opening bracket needs its matching close. A[Start without ] will fail silently or look broken.
Inconsistent arrow syntax. Mixing up --> and -> or forgetting the dashes causes parse errors. Stick with the documented patterns.
Overcrowded diagrams. A single flowchart with 40 nodes is hard to read. Break it into subgraphs or multiple diagrams linked together.

Some notations can overlap with UML diagram conventions, which adds confusion. If you're unsure about the difference, the comparison between UML and standard flowchart notation explains how the two approaches differ.

How Do You Style a Mermaid Flowchart?

Mermaid supports inline styling using style and classDef directives. Here's an example:

flowchart TD A[Start] --> B[Process] B --> C[Error] style C fill:#f96,stroke:#333

This fills the "Error" node with a light orange background. You can also define reusable styles:

classDef success fill:#6b6,stroke:#333,color:#fff classDef error fill:#f66,stroke:#333,color:#fff class A success class C error

Styling is optional, but it helps when you need to highlight specific steps, flag errors, or distinguish between happy-path and exception-path nodes in a workflow diagram.

Where Does Mermaid Flowchart Code Actually Work?

Mermaid diagrams render in several popular platforms and tools:

GitHub Mermaid code blocks in .md files render natively in pull requests, issues, and README files.
GitLab Also supports Mermaid rendering in markdown.
Notion You can embed Mermaid diagrams using code blocks.
VS Code Extensions like "Mermaid Preview" render diagrams as you type.
Obsidian Native Mermaid support in markdown notes.
Hugo, Docusaurus, MkDocs Most static site generators support Mermaid through plugins.

The official Mermaid documentation lists all supported platforms and the latest syntax updates.

Practical Checklist: Getting Started With Mermaid Flowcharts

Pick your platform (GitHub, VS Code, Obsidian, etc.) and verify Mermaid support.
Write a flowchart TD block with three nodes and two connections as a test.
Use the diamond shape {} for any decision points in your process.
Add arrow labels with the |text| syntax to clarify branching conditions.
Wrap related nodes in subgraph blocks if your diagram exceeds 10 nodes.
Apply style or classDef only after the structure is correct styling should come last.
Test rendering by pasting your code into the Mermaid Live Editor before committing it.
Keep each diagram focused on one process. If it starts sprawling, split it into separate linked diagrams.

Start with a single real workflow you already understand a login flow, an order process, a deployment pipeline and write it out in Mermaid. You'll have a working flowchart diagram in minutes, and you can iterate from there.