Mermaid.js Tips & Tricks: 15 Pro Shortcuts for Faster Diagrams (2026)

1. Use `flowchart` Instead of `graph`

The old graph TD still works, but flowchart TD unlocks newer features like direction inside subgraphs, markdown in nodes, and better rendering. Always prefer it:

flowchart TD
    A[Start] --> B[Process]

2. Markdown Inside Nodes

Wrap node labels in backtick-quotes and use
for line breaks:

flowchart TD
    A["**Bold** and *italic*<br/>Second line"]

This works in flowcharts, mindmaps, and most diagram types.

3. Quick Comments with `%%`

Add comments anywhere — they're ignored by the renderer:

flowchart TD
    %% This is a comment
    A --> B

4. Theme Toggle in One Line

Switch themes per-diagram without changing global settings:

%%{init: {'theme': 'dark'}}%%
flowchart LR
    A --> B

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

5. Custom Colors with `themeVariables`

Go beyond built-in themes — override specific colors:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ff6b6b', 'primaryTextColor': '#fff', 'lineColor': '#4ecdc4'}}}%%
flowchart LR
    A[Custom colored node] --> B[Another node]

6. Reuse Styles with `classDef`

Define a style once, apply it everywhere:

flowchart TD
    A:::highlight --> B:::highlight --> C
    classDef highlight fill:#ff0,stroke:#333,stroke-width:3px

7. `autonumber` in Sequence Diagrams

Never manually number steps again:

sequenceDiagram
    autonumber
    Client->>Server: GET /api/users
    Server-->>Client: 200 OK

8. Activation Bars in Sequences

Show when a participant is actively processing:

sequenceDiagram
    Client->>+Server: Request
    Server->>+DB: Query
    DB-->>-Server: Result
    Server-->>-Client: Response

+ activates, - deactivates. Nest them for call stacks.

9. `direction` Inside Subgraphs

Control the internal layout of subgraphs independently:

flowchart TB
    subgraph frontend["Frontend (Left-to-Right)"]
        direction LR
        A[React] --> B[Vue]
    end
    subgraph backend["Backend (Top-to-Bottom)"]
        direction TB
        C[API] --> D[DB]
    end

10. Emoji in Labels

Mermaid supports emoji directly in node labels:

flowchart LR
    A[🚀 Deploy] --> B[✅ Test] --> C[📦 Release]

11. Escape Special Characters

Wrap labels containing parentheses or brackets in quotes:

flowchart LR
    A["Method(param: string): void"] --> B

12. Click Events for Interactive Diagrams

Make nodes clickable — pairs perfectly with the Mermaid Live Editor:

flowchart LR
    A[Homepage]
    B[Docs]
    click A "https://example.com" "Go to homepage"
    click B "https://example.com/docs" "Read docs"

13. The `end` Note Placement Trick

Place notes exactly where you want them in state diagrams:

stateDiagram-v2
    state "Processing" as P
    note right of P: Triggers webhook

14. `showData` for Pie Charts

Add raw values to pie slices:

pie showData title Traffic Sources
    "Organic" : 55
    "Direct" : 25
    "Social" : 20

15. Use the Live Editor for Instant Preview

The fastest feedback loop: paste Mermaid code, see it render instantly. Split-pane mode lets you iterate at speed. Try it now →

Bonus: Keyboard Shortcuts (Mermaid Live Editor)

Pro tip: keep the live editor open in a pinned tab while writing docs — paste, tweak, copy the SVG, move on.

Open the free Mermaid Live Editor →