Mermaid Flowchart Syntax Examples and Usage

If you've ever needed to explain a process, system, or decision flow to someone a teammate, a client, or even your future self you know how painful it is when a static screenshot of a diagram gets buried in a Slack thread or email chain. Mermaid solves that. It lets you write flowcharts as plain text, which means your diagrams live right next to your code, your docs, or your markdown files. They're version-controlled, editable, and always reproducible. That's why understanding Mermaid flowchart syntax is worth your time: it turns diagrams from throwaway images into living documentation.

What exactly is Mermaid flowchart syntax?

Mermaid is a JavaScript-based diagramming tool that uses a text-based syntax to render diagrams including flowcharts, sequence diagrams, Gantt charts, and more. The flowchart syntax specifically lets you define nodes (shapes), links (arrows), and subgraphs using simple text rules.

Instead of dragging boxes around in a GUI tool, you write short declarations like this:

graph TD A[Start] --> B{Is it valid?} B -->|Yes| C[Process] B -->|No| D[Reject]

That text renders into a flowchart with a start node, a decision diamond, and two outcome branches. No mouse, no layout fights, no exported PNGs that nobody can edit later.

Mermaid is supported in GitHub markdown, GitLab, Notion, Obsidian, VS Code, Confluence, and many other tools. The official Mermaid documentation covers the full specification if you want the complete reference.

How do you define nodes and shapes in Mermaid?

Nodes are the building blocks of any Mermaid flowchart. The shape of a node is determined by the brackets you wrap around its text:

Rectangle: A[Text] uses square brackets
Rounded rectangle: A(Text) uses parentheses
Circle: A((Text)) uses double parentheses
Rhombus (diamond): A{Text} uses curly braces, typically for decisions
Stadium shape: A([Text]) rounded ends like a pill
Hexagon: A{{Text}} double curly braces
Parallelogram: A[/Text/] forward slashes
Subroutine: A[[Text]] double square brackets

You can also define a node without assigning it an ID. If you write graph TD and then use A[Start] --> B[End], Mermaid creates two nodes: one named "Start" with ID A, and one named "End" with ID B.

For a quick visual reference of these shapes, we put together a flowchart syntax cheat sheet that covers all the shape types in one place.

How do you connect nodes with arrows and links?

Links between nodes use arrow syntax. Here are the most common patterns:

Solid arrow: A --> B standard directional link
Open link (no arrow): A --- B connects without direction
Dotted arrow: A -.-> B dashed line with arrow
Thick arrow: A ==> B bold line with arrow
Link with text: A -->|Label| B adds a text label on the link

You can chain links too. Writing A --> B --> C --> D creates a straight sequence without needing to repeat the arrow for each step. This keeps your syntax clean when you have linear flows.

What does a complete Mermaid flowchart example look like?

Here's a practical example a user login flow that checks credentials and handles errors:

graph TD A[User visits login page] --> B[Enter credentials] B --> C{Valid format?} C -->|No| D[Show validation error] D --> B C -->|Yes| E{Credentials correct?} E -->|Yes| F[Redirect to dashboard] E -->|No| G[Show login error] G --> B

This flow uses decision diamonds for two checks, loops back to the input step on failure, and shows a happy path to the dashboard. It's the kind of diagram that would take five minutes to draw in a tool like Lucidchart but only takes seconds to write in Mermaid syntax.

How do subgraphs work in Mermaid flowcharts?

Subgraphs let you group related nodes into a labeled section. This is useful when you want to visually separate parts of a system like "Frontend," "Backend," and "Database."

graph TD subgraph Frontend A[User Interface] --> B[Form Submit] end subgraph Backend C[API Endpoint] --> D[Validate Input] end B --> C

You declare a subgraph with subgraph Name, place nodes inside, and close it with end. The rendered diagram draws a box around the grouped nodes with the label you chose.

How do you change the direction of a Mermaid flowchart?

The first line of your flowchart declaration sets the direction. You have four options:

graph TD Top to Down (most common)
graph LR Left to Right
graph BT Bottom to Top
graph RL Right to Left

You can also use flowchart instead of graph. The flowchart keyword supports additional features like link styles and more flexible node shapes. For most simple diagrams, graph TD and graph LR cover what you need.

What are common mistakes people make with Mermaid syntax?

Mermaid's syntax is simple, but small errors can break your entire diagram. Here are the most frequent issues:

Forgetting the direction declaration. Every flowchart needs graph TD (or LR, etc.) as the first line. Without it, Mermaid won't render anything.
Special characters in node text. Characters like {}, (), [], and # inside labels can confuse the parser. Wrap problematic text in quotes: A["Does it work? {Yes/No}"].
Inconsistent arrow syntax. Mixing --> and -> in the same chart won't work. Stick to Mermaid's supported arrow formats.
Missing end keyword for subgraphs. Every subgraph block must close with end. Forgetting this causes the rest of your chart to get absorbed into the subgraph.
Using spaces in node IDs. IDs must be single words (like A, loginStep, node1). The visible label can have spaces, but the ID cannot: loginStep[Login Step] works, but login step[Login Step] does not.

If you're just getting started and want a gentler walkthrough of the basics, check out our beginner's guide to flowchart code syntax.

Can you style Mermaid flowcharts with CSS or themes?

Yes. Mermaid supports built-in themes default, forest, dark, and neutral which you set in the initialization config. You can also apply custom styles to individual nodes:

graph TD A[Start] --> B[End] style A fill:#f9f,stroke:#333,stroke-width:2px style B fill:#bbf,stroke:#333,stroke-width:2px

The style keyword accepts CSS-like properties. You can change fill color, stroke, border radius, and more. If you want to apply a style to many nodes at once, use classDef to define a class and class to assign it:

graph TD A[Step 1] --> B[Step 2] classDef highlight fill:#ff9,stroke:#333 class A,B highlight

Where can you actually use Mermaid flowcharts?

Mermaid diagrams render in a growing list of tools and platforms:

GitHub: Mermaid blocks in markdown files and README files render automatically since 2022.
GitLab: Supported in wiki pages, markdown files, and issues.
VS Code: Extensions like "Mermaid Markdown Syntax Highlighting" and "Markdown Preview Mermaid Support" let you preview diagrams while you write.
Obsidian: Native Mermaid support inside code blocks just use ```mermaid.
Notion: Use the code block with Mermaid language selection.
Confluence: Via the Mermaid macro or third-party apps.

This portability is one of the biggest advantages. You're not locked into a proprietary diagram tool. Your flowchart is plain text you can copy, paste, and render anywhere Mermaid is supported.

How do you add links and click events in Mermaid flowcharts?

Mermaid lets you attach URLs to nodes so readers can click through to related pages:

graph TD A[Docs] --> B[API Reference] click A "https://example.com/docs" "Open docs"

The click keyword takes a node ID, a URL, and an optional tooltip text. Note that some platforms (like GitHub) disable click interactivity for security reasons, so test where you plan to publish.

For a deeper dive into all available syntax features, we have a full reference on Mermaid flowchart syntax examples and usage.

Quick checklist before you publish your Mermaid flowchart

Does the first line declare a direction? (graph TD or flowchart LR)
Are all node IDs single words with no spaces?
Are special characters inside node labels wrapped in quotes?
Does every subgraph have a matching end?
Are arrow styles consistent throughout the chart?
Have you tested rendering in the platform where you'll publish? (Mermaid Live Editor at mermaid.live is handy for this)
Is the flow direction logical for your audience top-down for processes, left-to-right for timelines?
If you used click events, do they work in your target platform?

Paste your diagram into the Mermaid Live Editor to test it before committing. It catches syntax errors and gives you a live preview, which saves time compared to guessing and pushing broken markdown.