What direction should I use for a Mermaid flowchart — TD or LR?

Use `TD` (top-down) for tall processes that read vertically — approval flows, validation pipelines, anything where the natural reading direction is downward. Use `LR` (left-to-right) for slide-deck destinations where horizontal space exceeds vertical, or when the diagram has many parallel branches that would stack awkwardly tall in TD. `RL` and `BT` exist but are rarely the right choice.

How do I add a decision branch in a Mermaid flowchart?

Use `A{Question?}` to declare a diamond decision node, then label the outgoing edges with `A -- Yes --> B` and `A -- No --> C` (or the equivalent pipe syntax `A -->|Yes| B`). The shape signals the branch and the labels tell readers which outcome leads where. Both outcomes remain visually distinct after beautifying.

What's the difference between solid, dotted, and thick arrows?

Solid `-->` is the default direct flow. Dotted `-.->` reads as asynchronous, weaker, or deferred — good for retries, registry lookups, or async dispatches you want to acknowledge but de-emphasise. Thick `==>` is for the primary path you want to call out — the happy path through a complex diagram. Reserve dotted and thick for genuinely different semantics; over-styling obscures the structure.

Can I group related nodes in a Mermaid flowchart?

Yes — use `subgraph Name ... end`. Subgraphs visually cluster related nodes (a module, a service, a phase). Edges can cross subgraph boundaries naturally, and you can even point an edge from or to a whole subgraph id when many edges share an endpoint. For deeper coverage of architecture-style flowcharts that lean on subgraphs, see the architecture-with-subgraph guide linked above.

Why does my flowchart label disappear?

Almost always because you re-declared the same node id with a different label. `A[First]` followed by `A` (with no label) keeps the first label, but `A[Second]` later overwrites it silently. Each node id should be declared with its label once, and referenced bare on subsequent lines. The other common cause: unescaped quotes or special characters inside labels — wrap in backticks or use HTML entities if you need them.

Diagram type

Mermaid Flowchart Syntax & Examples

Reference for Mermaid flowchart syntax — directions (TD/LR), node shapes, edge styles, decision branches, subgraphs, and labelled edges. Copy-paste examples.

Use this page to connect a high-intent search query to the right problem-solution narrative.

At a glance

A syntax reference for Mermaid's flowchart grammar — read this when you need to know the exact way to express a decision, loop, subgraph, or styled edge, then try the result in the editor.

What is a Mermaid flowchartDirection — TD, LR, RL, BTNode shapes — rectangles, rounds, diamonds, circlesEdges — arrows, labels, link stylesSubgraphs — groups of related nodesCommon patterns & gotchas

Rendered proof

A form-submission flow using a decision, a retry loop, and a confirmation outcome — exercises three of the most common flowchart constructs.

Theme · Memphis

Open this diagram in editor

View Mermaid sourcePlain-text diagram syntax — copy or edit directly.

diagram.mmd

1flowchart TD
2  A[Start] --> B{Is the form valid?}
3  B -- Yes --> C[Submit]
4  B -- No --> D[Show errors]
5  C --> E[Confirmation]
6  D --> A

Open in editor with this template

What is a Mermaid flowchart

A Mermaid flowchart is the most common diagram type in the Mermaid language — a directed graph where nodes represent steps and edges represent transitions. Every Mermaid flowchart starts with the `flowchart` (or legacy `graph`) keyword followed by a direction hint, and then a series of node and edge declarations. It is the right shape for any process where the question is what-happens-next: API request flows, validation pipelines, approval chains, retry logic, deployment pipelines. If your diagram is mostly about ordering of calls between actors, prefer a sequence diagram; if it is about who-owns-what across teams, prefer a swimlane. For everything else, flowchart is the default.

Direction — TD, LR, RL, BT

The first line declares the flow direction. `flowchart TD` (top-down) is the most common for tall vertical reading paths typical of process diagrams. `flowchart LR` (left-to-right) reads better on slide decks and wide canvases where horizontal space exceeds vertical. `RL` (right-to-left) and `BT` (bottom-to-top) exist but are rarely the right choice — they flip the reading axis against most readers' expectation. Mermaid uses the direction as a layout hint; complex source can be re-laid-out automatically by Beauty Diagram's pattern engine when the direction does not match the underlying flow shape.

`TD` / `TB` — top-down (default for vertical processes)
`LR` — left-to-right (best for slide decks)
`RL` / `BT` — niche, avoid unless the content is naturally reversed

Node shapes — rectangles, rounds, diamonds, circles

Each node shape signals a different semantic role. `A[Label]` is a rectangle (a standard step). `A(Label)` is a rounded rectangle (often used for terminals or soft steps). `A{Label}` is a diamond (a decision point). `A((Label))` is a circle (start / stop / state). `A[/Label/]` and `A[\Label\]` are parallelograms (input / output). `A[[Label]]` is a subroutine. `A>Label]` is an asymmetric flag. The shape carries information independent of the label, so use them deliberately — readers can identify a decision diamond before they finish reading the question inside it.

`A[Step]` — rectangle (default step)
`A{Decision?}` — diamond (decision / branch)
`A((State))` — circle (start / stop / terminal state)
`A([Round])` — stadium shape (soft step)

Edges — arrows, labels, link styles

Edges connect nodes and carry the direction of flow. `A --> B` is a solid arrow (the default). `A -- Label --> B` and `A -->|Label| B` both attach a label to the edge. `A --- B` is an undirected line (rare). `A -.-> B` is a dotted arrow for asynchronous or weaker dependencies. `A ==> B` is a thick arrow for emphasised paths. `A x-- B` and `A o-- B` use cross and circle endpoints (less common). The edge style is read as fast as the node shape, so reserve dotted/thick edges for genuinely different semantics — a sea of mixed styles obscures the structure.

Subgraphs — groups of related nodes

Subgraphs group nodes that belong together — a module, a service, a phase. Declare with `subgraph Name` and close with `end`. Inside, nodes are declared the same way as the outer graph; cross-boundary edges (edges that reference a node id in another subgraph or the outer graph) are how subgraphs communicate with the rest of the diagram. Subgraphs accept a labelled form `subgraph Name["Display Title"]` when the id and the visible title should differ. Mermaid lets you point an edge from a whole subgraph id (e.g. `Channels ==> Gateway`), which the renderer treats as routing from a representative member of the cluster — useful when many components funnel into the same target.

`subgraph Name ... end` — basic group
`subgraph Name["Display Title"]` — separate id and visible title
Cross-subgraph edges connect modules; edges can also start or end at a whole subgraph id

Common patterns & gotchas

Three patterns appear in almost every real flowchart: decision-with-two-outcomes (`A{Q?} -- Yes --> B`), retry loop (`Worker --> Done; Worker -->|retry| Queue`), and module handoff (subgraph-to-subgraph edge). The most common gotcha: forgetting that node ids and node labels are separate — `A[Label]` declares the id once with a label, and `A` on later lines refers to the same node. Re-declaring with a different label silently overwrites the first one. Second gotcha: quotes inside labels need either backticks or HTML entities; raw double-quotes break the parser.

Re-declaring a node id with a different label silently overwrites the original label
Use `<br/>` inside labels for line breaks (Mermaid's official break)
Cluster-as-endpoint edges (`Subgraph ==> Node`) route from a representative member