Mermaid Viewer

Reference

Mermaid Syntax Guide — Complete Reference

Everything you need to write Mermaid diagrams. From basic syntax rules to advanced configuration options — a single reference page for all diagram types.

Supported Diagram Types

Mermaid supports 10+ diagram types. Declare the type at the start of your code:

graphFlowchart — nodes and edges
flowchartAlias for graph (recommended)
sequenceDiagramSequence diagram — actors and messages
piePie chart — data visualization
classDiagramClass diagram — UML class structure
stateDiagramState diagram — finite state machine
entityRelationshipDiagramER diagram — database entities
ganttGantt chart — project timeline
gitGraphGit graph — repository commits
requirementDiagramRequirement diagram — system requirements

Flowchart Direction

Control how nodes are arranged and connected:

Syntax

graph TD    # Top to Down (default)
graph TB    # Top to Bottom
graph BT    # Bottom to Top
graph LR    # Left to Right
graph RL    # Right to Left

flowchart TD    # "flowchart" keyword also works

Node Shapes

The shape of a node determines its semantic meaning:

A[Text]RectangleProcess / Action
A(Text)RoundedRoutine / Subroutine
A((Text))CircleStart / End point
A{Text}DiamondDecision / Condition
A[[Text]]SubroutineFunction / Method
A[(Text)]CylinderDatabase
A{{Text}}HexagonPreparation / Alternate process
A[/Text/]Trapezoid (right)Manual operation
A[\Text\]Trapezoid (left)Manual operation
A[(Text)]Circle (alt)Start / End marker

Arrows & Links

Connect nodes with different line and arrow styles:

Syntax

A --> B        "Solid arrow"
A --- B        "Plain line (no arrow)"
A -.-> B       "Dotted arrow"
A -. - B       "Dotted line (no arrow)"
A ==> B        "Thick arrow"
A ==>= B       "Extra thick arrow"
A -->|text| B  "Arrow with label"
A o--o B       "Open circle ends"
A *--* B       "Diamond ends"
A --o B        "One circle end"
A --* B        "One diamond end"
A x-- B        "Cross end"

subgraph A     "Group nodes in container"
  B --> C
end

Node IDs & Labels

Syntax

# ID equals label
graph TD
    A --> B

# ID different from label
graph TD
    A[Start] --> B[End]
    step1[Validate input] --> step2[Process data]

# Multi-word labels (no quotes needed)
graph TD
    Start --> Middle[Wait for response]
    Middle --> End

Themes

Change the visual style of your diagrams:

Syntax

%%{init: {'theme':'base'}}%%
%%{init: {'theme':'dark'}}%%
%%{init: {'theme':'forest'}}%%
%%{init: {'theme':'neutral'}}%%
%%{init: {'theme':'night'}}%%
%%{init: {'theme':'default'}}%%

%% Custom theme variables %%
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#cdb4db'}}}%%

Comments

Syntax

%% Single-line comment
%%
%% This entire line is a comment
graph TD
    A --> B %% inline comment (ignored)

Common Pitfalls

❌ Special characters in labels

→ Use double quotes: A["Hello & Goodbye"] --> B

❌ Very long node labels

→ Keep labels under 40 chars. Long text wraps awkwardly in small nodes.

❌ Arrow labels with pipes

→ Use |label|: A -->|yes| B or A --> B|: label}

❌ Duplicate node IDs

→ Each ID must be unique. Use descriptive IDs: loginBtn instead of btn1.

❌ HTML entities not rendered

→ Mermaid does not support HTML in labels. Stick to plain text and Unicode symbols.

❌ Diagrams too wide

→ Use graph LR instead of graph TD for wide flows, or use subgraphs to group.

Quick Examples by Type

Flowchart

graph TD
    A[Start] --> B{Is it broken?}
    B -->|Yes| C[Fix it]
    B -->|No| D[Good to go]
    C --> D

Sequence Diagram

sequenceDiagram
    User->>API: POST /submit
    activate API
    API-->>User: 200 OK
    deactivate API

Pie Chart

pie title Traffic Sources
    "Search" : 450
    "Social" : 280
    "Direct" : 170

Try Mermaid syntax now

No signup required. Open mermaid.bkkdev.io and start experimenting.

Open Mermaid Viewer →