Mermaid Flowchart advanced: node shapes, edges, Subgraph grouping, and Layout directions

Mermaid’s Flowchart is its flagship feature — closer to hand-drawn diagrams than PlantUML’s Activity diagram. This post covers everything: shapes, edges, Subgraph, directions, styling, and how it compares to PlantUML.

Why Flowchart instead of Activity diagram

PlantUML’s activity diagram is strict UML — filled circle for start/end, diamonds for decisions, fork/join for concurrency. Correct, but rigid.

Mermaid Flowchart is hand-drawn style — rectangles, diamonds, cylinders, stadium shapes, whatever fits your meaning. Great for:

• Business process diagrams (not software modeling)
• Decision trees
• Architecture topology
• Documentation illustrations

One-liner

1
2

flowchart LR
    A --> B

• flowchart keyword + LR sets direction (left→right)
• Default nodes are rounded rectangles
• --> is a solid arrow

Directions

1
2

flowchart TB
    Top --> Middle --> Bottom

1
2

flowchart RL
    Right --> Middle --> Left

Recommendation: TB (top-to-bottom) by default — matches English reading order. LR for wide but shallow flows.

Node Shapes

10+ shapes, each indicated by a suffix on the node ID:

Default (rounded rectangle)

1

A[text here]

Stadium (rounded, pill-shaped)

1

A(Stadium shape)

Subroutine (stadium, used for programs/modules)

1

A[[Subroutine]]

Decision (diamond)

1

A{Decision?}

Cylinder (database)

1

A[(Cylinder)]

Circle

1

A((Circle))

Hexagon

1

A{{Hexagon}}

Parallelogram (data input)

1

A[/Parallelogram/]

Trapezoid (process)

1

A[/Trapezoid\]

All shapes at once

1
2
3
4
5
6
7
8
9
10
11

flowchart LR
    subgraph Shapes
        direction LR
        A[Default] --> B(Stadium)
        B --> C[[Cylinder]]
        C --> D{Decision}
        D --> E((Circle))
        E --> F{{Hexagon}}
        F --> G[/Parallelogram/]
        G --> H[/Trapezoid\]
    end

Note: direction can only be declared once per flowchart (at the first occurrence). Subgraph children can override locally.

Edge Types

Basic edges

Chain syntax

1
2

flowchart LR
    A --> B --> C --> D

Bifurcation (multiple outgoing edges)

1
2
3
4
5

flowchart TD
    Start --> Decision{Success?}
    Decision -->|Yes| Success
    Decision -->|No| Failure
    Decision -->|Retry| Retry

|Yes| and |No| are edge labels placed between the arrow symbol and the target: --|label| target.

Convergence (multiple incoming edges)

1
2
3
4

flowchart LR
    A --> C
    B --> C
    C --> D

Dotted styles

1
2
3
4

flowchart LR
    A -.-> B
    B -. dotted .-> C
    C ==> D

More dots = thicker line. -. dotted .-> renders noticeably thicker than -.->.

Bidirectional

1
2

flowchart LR
    A <--> B

Subgraph (grouping nodes)

Subgraph is the most powerful Flowchart feature — group related nodes inside a labeled box.

Basic Subgraph

1
2
3
4
5
6
7
8

flowchart TB
    subgraph Frontend
        A[Vue] --> B[Router]
    end
    subgraph Backend
        C[Node] --> D[(Database)]
    end
    A --> C

With display label

1
2
3
4
5
6
7
8

flowchart TB
    subgraph clusterFrontend [Frontend Module]
        A[Vue] --> B[Pinia]
    end
    subgraph clusterBackend [Backend Module]
        C[API] --> D[(DB)]
    end
    B --> C

Format: subgraph ID [Display Label]. The cluster prefix is an optional styling decorator.

Subgraph with internal direction

1
2
3
4
5

flowchart TB
    subgraph LoginFlow
        direction LR
        Input --> Validate --> Success
    end

Override the parent direction inside a specific Subgraph — useful when one group is wide.

Real-world: e-commerce checkout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

flowchart TD
    subgraph Client
        A[Browse] --> B[Add to Cart]
        B --> C[Submit Order]
    end
    subgraph Server
        D[Receive Order] --> E{Available?}
        E -->|Yes| F[Reserve Stock]
        E -->|No| G[Out of Stock]
        F --> H[Create Order Record]
    end
    subgraph Payment
        H --> I{Payment OK?}
        I -->|Yes| J[Ship]
        I -->|No| K[Cancel Order]
    end
    C --> D
    J --> L[User Confirms]

Three Subgraphs clearly separate concerns — 10× more readable than one flat diagram.

Node ID Naming Rules

What you can use

• Letters: A, node1
• Numbers: 1, step3
• Chinese characters: 开始, 判断 (no quotes needed)
• Mixed: userLogin, order_submit

What you cannot use

• Spaces in unquoted IDs: A --> B C parses B C as two nodes. Use A --> B then B --> C
• Commas, semicolons, # — special characters in Mermaid
• Bare quotes — wrap properly

Quoting names with spaces or special chars

1
2
3

flowchart LR
    "Node A" --> "Node B"
    "Special #1" --> "Contains; semicolon"

Common errors

Styling

Per-node style

1
2
3

flowchart LR
    A --> B
    style A fill:#f9f,stroke:#333,stroke-width:4px

style applies fill:, stroke:, stroke-width: to a single node.

Class-based styling (multiple nodes)

1
2
3
4
5

flowchart LR
    A --> B
    B --> C
    classDef highlight fill:#f96,stroke:#333,stroke-width:4px
    class B highlight

classDef names a style; class applies it to nodes. Cleaner than inline style for reusable styles.

Themes

1
2
3

%%{init: {'theme': 'dark'}}%%
flowchart TD
    A[Dark theme] --> B[Rounded rectangle]

Available themes: default, forest, dark, neutral, base.

Full styled example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

flowchart TD
    subgraph Auth
        A{Logged in?} -->|Yes| B[Get Token]
        A -->|No| C[Redirect to Login]
    end
    
    subgraph Data
        B --> D[(Query DB)]
        D --> E{Has data?}
        E -->|Yes| F[Return data]
        E -->|No| G[Return empty]
    end
    
    style A fill:#ff6b6b,stroke:#333,stroke-width:2px
    style E fill:#ffd93d,stroke:#333,stroke-width:2px
    style D fill:#6bcb77,stroke:#333,stroke-width:2px

Mermaid-exclusive features PlantUML doesn’t have

Git Graph

1
2
3
4
5
6
7
8
9

gitGraph
    commit id: "init"
    commit id: "add feature A"
    branch feature
    checkout feature
    commit id: "WIP"
    checkout main
    commit id: "fix bug"
    merge feature id: "merge"

No PlantUML plugin needed — native Mermaid.

Requirement Diagram

1
2
3
4
5
6
7
8
9
10
11
12
13
14

requirementDiagram
    
    requirement TestReq {
        id: 1
        text: "System must respond within 100ms"
        risk: high
        verifymethod: test
    }
    
    element entity {
        type: simulation
    }
    
    entity --> TestReq

Pie Chart

1
2
3
4
5
6

pie title Language distribution
    "JavaScript" : 42
    "Python" : 27
    "TypeScript" : 18
    "Go" : 8
    "Other" : 5

All three work without any plugin or workaround.

Common errors and debug

Loop references

1
2
3
4

flowchart LR
    A --> B
    B --> C
    C --> A

Loops are fine — Mermaid handles them. If the graph is too tangled, it warns “too many nodes, simplify”.

direction inside Subgraph (wrong position)

1
2
3
4
5

flowchart TB
    subgraph Example
        A --> B
        direction LR
    end

direction after node definitions is ignored. Place it first inside the Subgraph:

1
2
3
4
5

flowchart TB
    subgraph Example
        direction LR
        A --> B
    end

Recap

5 things to remember from Mermaid Flowchart:

1. Direction: TB is the default and usually sufficient
2. Shapes: [rect] (rounded) {diamond} ((circle)) [[cylinder]] — shape carries meaning
3. Edges: --> is arrow, --- is line, -.-> is dotted, ==> is thick
4. Subgraph: the key tool for keeping complex diagrams readable
5. Style: classDef for reusable styles, style for one-offs, theme via %%{init:{'theme':'dark'}}%%

PlantUML has no native Flowchart — only Activity diagram. Different tools for different jobs. For business flows, decision trees, documentation illustrations → Mermaid Flowchart.