Mermaid Syntax Guide: The Complete Reference

What Is Mermaid?

Mermaid is an open-source JavaScript library that turns text-based definitions into diagrams and charts. Instead of dragging shapes around in a visual editor, you describe your diagram using a concise, readable syntax, and Mermaid renders it into a polished SVG graphic. The syntax is intentionally simple: if you can write Markdown, you can write Mermaid.

Mermaid has become the standard for diagrams in developer documentation. GitHub renders Mermaid blocks natively inside Markdown files, GitLab does the same, and tools like Notion, Obsidian, and Docusaurus all support it. This guide covers every major diagram type with examples you can copy directly into our Mermaid Diagram Renderer to see them rendered instantly.

Flowcharts

Flowcharts are the most commonly used Mermaid diagram type. They describe processes, decision trees, and workflows using nodes connected by edges. Mermaid supports both top-down (TD/TB) and left-right (LR) orientations.

Basic Syntax

flowchart TD
    A[Rectangle Node] --> B(Rounded Node)
    B --> C{Diamond Decision}
    C -->|Yes| D[Result A]
    C -->|No| E[Result B]

Node Shapes

Mermaid provides several node shapes, each conveyed through bracket syntax. The shape you choose communicates the semantic purpose of each step in your diagram.

flowchart LR
    A[Rectangle]         %% Standard process step
    B(Rounded)           %% Alternative process
    C([Stadium])         %% Start/end terminal
    D[[Subroutine]]      %% Subroutine or function call
    E[(Database)]        %% Data store / database
    F((Circle))          %% Connector point
    G{Diamond}           %% Decision / conditional
    H{{Hexagon}}         %% Preparation step
    I[/Parallelogram/]   %% Input / output

Edge Types

flowchart LR
    A --> B               %% Arrow
    C --- D               %% Line (no arrow)
    E -.- F               %% Dotted line
    G -.-> H              %% Dotted arrow
    I ==> J               %% Thick arrow
    K -->|label| L        %% Arrow with text

Subgraphs

Subgraphs group related nodes visually and can be nested. They are useful for representing systems, services, or logical boundaries.

flowchart TB
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        C[REST API] --> D[(PostgreSQL)]
    end
    B --> C

Sequence Diagrams

Sequence diagrams show interactions between actors or systems over time. They are the standard way to document API flows, authentication handshakes, and inter-service communication.

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: POST /api/users
    activate S
    S->>DB: INSERT INTO users
    activate DB
    DB-->>S: OK (user_id: 42)
    deactivate DB
    S-->>C: 201 Created
    deactivate S

Message Types

sequenceDiagram
    A->>B: Solid arrow (synchronous)
    A-->>B: Dashed arrow (async response)
    A-xB: Solid cross (lost message)
    A--xB: Dashed cross
    A-)B: Open arrow (async)
    A--)B: Dashed open arrow

Loops, Alternatives, and Notes

sequenceDiagram
    participant U as User
    participant A as App

    loop Every 30 seconds
        A->>A: Health check
    end

    alt Authenticated
        U->>A: Access dashboard
    else Guest
        U->>A: Redirect to login
    end

    Note over U,A: Session timeout after 30 min

Class Diagrams

Class diagrams model the structure of object-oriented systems. They show classes, their attributes, methods, and the relationships between them. This is the diagram type most familiar to anyone who has worked with UML.

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean indoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Relationship Types

classDiagram
    A <|-- B : Inheritance
    C *-- D : Composition
    E o-- F : Aggregation
    G --> H : Association
    I ..> J : Dependency
    K ..|> L : Realization

Entity-Relationship Diagrams

ER diagrams describe database schemas and the relationships between tables. They are invaluable for planning database designs and documenting existing schemas.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"

    CUSTOMER {
        int id PK
        string name
        string email UK
    }
    ORDER {
        int id PK
        date created_at
        int customer_id FK
    }
    LINE_ITEM {
        int order_id FK
        int product_id FK
        int quantity
    }
    PRODUCT {
        int id PK
        string name
        decimal price
    }

Cardinality Notation

ER diagrams use a compact notation to express relationship cardinality between entities.

%% ||--|| : exactly one to exactly one
%% ||--o{ : exactly one to zero or more
%% ||--|{ : exactly one to one or more
%% }o--o{ : zero or more to zero or more

State Diagrams

State diagrams model the lifecycle of an object or process, showing the states it can be in and the transitions between them. They are particularly useful for describing UI state machines, order processing, and protocol specifications.

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Approved : Approve
    Review --> Draft : Request changes
    Approved --> Published : Publish
    Published --> Archived : Archive
    Archived --> [*]

    state Review {
        [*] --> Pending
        Pending --> InReview : Assign reviewer
        InReview --> Pending : Unassign
    }

Gantt Charts

Gantt charts display project timelines with tasks, durations, and dependencies. They are useful for sprint planning, project proposals, and release schedules.

gantt
    title Project Launch Timeline
    dateFormat  YYYY-MM-DD
    excludes    weekends

    section Design
    Wireframes           :done, des1, 2026-03-01, 5d
    Visual Design        :active, des2, after des1, 7d
    Design Review        :des3, after des2, 2d

    section Development
    Frontend             :dev1, after des2, 10d
    Backend API          :dev2, after des1, 12d
    Integration          :dev3, after dev1, 5d

    section Testing
    QA Testing           :test1, after dev3, 5d
    Bug Fixes            :test2, after test1, 3d

    section Launch
    Deployment           :milestone, after test2, 0d

Pie Charts

Pie charts provide a simple way to visualize proportional data. While not as common as flowcharts or sequence diagrams, they are useful for presentations and dashboards.

pie title Technology Stack
    "TypeScript" : 45
    "Python" : 25
    "Go" : 15
    "Rust" : 10
    "Other" : 5

Mindmaps

Mindmaps visualize hierarchical ideas radiating from a central concept. They are useful for brainstorming, knowledge organization, and meeting notes.

mindmap
    root((DevOps))
        CI/CD
            GitHub Actions
            Jenkins
            GitLab CI
        Containers
            Docker
            Kubernetes
            Podman
        Monitoring
            Prometheus
            Grafana
            Datadog
        Infrastructure
            Terraform
            Ansible
            Pulumi

Quick Reference Table

This table summarizes the opening keyword for each diagram type and its primary use case.

Styling and Theming

Mermaid supports inline styling using the style keyword and CSS class assignments. You can change node colors, borders, and text styles directly within the diagram definition.

flowchart LR
    A[Default] --> B[Styled]
    style B fill:#06d6a0,stroke:#333,stroke-width:2px,color:#000
    style A fill:#f9f,stroke:#333,color:#000

For consistent theming across your diagrams, Mermaid provides built-in themes: default, dark, forest, and neutral. Our Mermaid Renderer lets you switch between themes instantly to see how your diagram looks in each one.

Common Pitfalls

When writing Mermaid syntax, a few common mistakes can cause unexpected rendering failures. Here are the most frequent issues and their solutions:

• Special characters in labels: Wrap node text in quotes if it contains parentheses, brackets, or other special characters: A["Process (v2)"]
• Indentation sensitivity: While Mermaid is not strictly indentation-sensitive, consistent indentation makes diagrams much easier to read and maintain.
• Missing direction keyword: Flowcharts require a direction (TD, TB, LR, RL, BT). Omitting it may cause rendering errors.
• Comments: Use %% for comments. Regular // or # comments are not supported.
• Node ID reuse: Each node ID should be defined with its shape only once. Subsequent references use just the ID without brackets.

Ready to try these examples interactively? Open our Mermaid Diagram Renderer and paste any code block from this guide to see it rendered live. You can also explore our real-world flowchart examples for practical patterns you can adapt to your own projects.