Mermaid Flowchart Syntax Guide (Complete Reference)

Flowcharts are the most-used Mermaid diagram type, and their syntax is worth knowing thoroughly because a little fluency lets you sketch logic almost as fast as you can think it. This guide is a complete reference: node shapes, the full range of arrow styles, layout directions, subgraphs for grouping, and styling. Each section includes short, correct snippets you can copy directly. Keep the live editor at /diagram-tools/mermaid-editor open and paste these in to see each one render.

A Mermaid flowchart begins with either `flowchart` or the older `graph` keyword, followed by a direction. `flowchart TD` draws top-down, `flowchart LR` draws left-to-right. Everything after that first line defines nodes and the connections between them. The elegant thing about the syntax is that defining a connection also defines the nodes it touches, so `A --> B` creates both nodes and the arrow in one line - you rarely declare nodes separately.

Node shapes

The shape of a node is determined by the brackets you wrap its label in. This is the core of Mermaid flowchart syntax and worth memorizing, because the shape carries meaning - a diamond signals a decision, a rounded box a start or end. Here are the shapes you will use most.

• `A[Square text]` - a rectangle, the default process step.
• `A(Rounded text)` - a rounded rectangle, often used for start and end.
• `A([Stadium text])` - a stadium/pill shape, another common terminator.
• `A{Diamond text}` - a diamond, used for decisions.
• `A[(Database)]` - a cylinder, for a data store or database.
• `A((Circle text))` - a circle, for connectors or special nodes.
• `A[/Parallelogram/]` - a parallelogram, for input or output.
• `A{{Hexagon}}` - a hexagon, for preparation or special steps.

Arrows and links

Connections come in several styles that convey different meanings. The basic arrow is `A --> B`, a solid line with an arrowhead. A line with no arrowhead is `A --- B`, used for associations without direction. A dashed arrow is `A -.-> B`, often for weaker or optional relationships, and a thick arrow is `A ==> B` for emphasis. Getting comfortable with these lets you distinguish primary flow from secondary relationships visually.

Labels on arrows go in the middle of the link. You can write `A -->|Yes| B` with the label between pipes, or the alternative form `A -- Yes --> B`. For a decision, this is essential: `B{Approved?} -->|Yes| C[Proceed]` and `B -->|No| D[Reject]` produce the two labelled branches every decision needs. You can also chain connections on one line - `A --> B --> C` - which is a compact way to express a linear sequence, and you can connect one node to several with `A --> B & C` to fan out.

Subgraphs and grouping

As flowcharts grow, grouping related nodes makes them far more readable, and Mermaid provides subgraphs for exactly this. You open a group with `subgraph Title`, put node definitions and connections inside, and close it with `end`. Mermaid draws a labelled box around everything in the subgraph, visually clustering it. This is how you show that a set of steps belongs to one phase, one system, or one team within a larger flow.

Subgraphs can be connected to each other and to nodes outside them, and you can even set a direction for a subgraph independently. They are the main tool for managing complexity in a Mermaid flowchart - rather than one flat sprawl of nodes, you organize the diagram into meaningful clusters. Combined with the ability to name nodes with short IDs and give them longer display labels, subgraphs let you keep even fairly large flowcharts comprehensible.

Styling and layout control

Mermaid flowcharts can be styled directly in the syntax. You apply a style to a node with a `style` line - `style A fill:#f9f,stroke:#333` sets a node's fill and border color. For reuse, you can define a named class with `classDef` and apply it to multiple nodes, which keeps styling consistent without repeating properties. This lets you color-code a diagram - say, error paths in red - to add a layer of meaning beyond the shapes.

Layout is mostly automatic, which is Mermaid's great convenience, but you do have levers. The direction keyword (`TD`, `LR`, and so on) sets the overall flow. The order in which you write connections influences layout. For most flowcharts, letting Mermaid lay things out is exactly what you want - it produces clean, consistent results without fuss. When you need precise control that the auto-layout cannot give, that is the moment to bring the diagram into a visual editor. Atlas Diagram Studio lets you import Mermaid and then adjust the layout by hand on the canvas at /diagrams, and you can build flowcharts visually from templates at /diagram-tools/flowchart-maker when direct manipulation suits the task better.