Mermaid.js Syntax Cheat Sheet for Developers

Mermaid.js lets you create diagrams from text — no drag-and-drop tools required. This cheat sheet covers the syntax for every major diagram type with copy-paste examples you can use immediately.

Each example below is valid Mermaid syntax. Paste any of them into the ImageToMermaid editor or a GitHub README to see them render.

Flowcharts

Flowcharts are the most common Mermaid diagram. Use flowchart followed by a direction:LR (left to right), TD (top down), RL, or BT.

flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Ship it]
    B -->|No| D[Debug]
    D --> B

Node Shapes

• A[Rectangle] — standard box
• A(Rounded) — rounded corners
• A({Oval}) — stadium/oval shape
• A{Diamond} — decision node
• A[[Subroutine]] — subroutine box
• A((Circle)) — circle

Arrow Types

• A --> B — solid arrow
• A -.-> B — dotted arrow
• A ==> B — thick arrow
• A -->|label| B — arrow with label
• A --- B — line (no arrow)

Subgraphs

flowchart LR
    subgraph Backend
        API[API Server] --> DB[(Database)]
    end
    subgraph Frontend
        UI[React App] --> API
    end

Sequence Diagrams

Sequence diagrams show interactions between participants over time. Great for documenting API flows and protocol exchanges. For a deeper comparison with flowcharts, see Flowchart vs Sequence Diagram.

sequenceDiagram
    participant Client
    participant Server
    participant DB

    Client->>Server: POST /api/login
    Server->>DB: SELECT user WHERE email = ?
    DB-->>Server: User record
    alt Valid credentials
        Server-->>Client: 200 OK + JWT
    else Invalid
        Server-->>Client: 401 Unauthorized
    end

Message Types

• -> — solid line without arrow
• ->> — solid line with arrow
• -->> — dotted line with arrow
• -x — solid line with cross (async)
• --x — dotted line with cross

Grouping

• loop Every 5s — loop block
• alt / else — conditional branches
• opt — optional block
• par / and — parallel execution
• Note over A,B: text — spanning note

ER Diagrams

Entity-Relationship diagrams define database schemas. For naming conventions and normalization guidance, see ER Diagram Best Practices.

erDiagram
    USERS {
        uuid id PK
        string email
        timestamp created_at
    }
    ORDERS {
        uuid id PK
        uuid user_id FK
        decimal total
        string status
    }
    ORDER_ITEMS {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        int quantity
    }
    PRODUCTS {
        uuid id PK
        string name
        decimal price
    }
    USERS ||--o{ ORDERS : places
    ORDERS ||--|{ ORDER_ITEMS : contains
    PRODUCTS ||--o{ ORDER_ITEMS : "is in"

Relationship Syntax

• ||--|| — one to one
• ||--o{ — one to many
• }{o--o{ — many to many
• |o--o| — zero or one to zero or one

Class Diagrams

UML class diagrams show classes, their attributes, methods, and relationships.

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +bool isIndoor
        +purr() void
    }
    Animal <|-- Dog
    Animal <|-- Cat

Relationship Types

• <|-- — inheritance
• *-- — composition
• o-- — aggregation
• --> — association
• ..> — dependency
• ..|> — realization/interface

Gantt Charts

Gantt charts visualize project timelines with tasks, durations, and dependencies.

gantt
    title Project Launch Timeline
    dateFormat YYYY-MM-DD
    section Design
        Wireframes           :done,    des1, 2026-01-01, 2026-01-14
        UI Mockups           :done,    des2, after des1, 14d
    section Development
        Frontend             :active,  dev1, 2026-02-01, 30d
        Backend API          :         dev2, 2026-02-01, 30d
        Integration Testing  :         dev3, after dev1, 14d
    section Launch
        Beta Release         :milestone, m1, after dev3, 0d
        Production Deploy    :         dep1, after m1, 7d

Pie Charts

Simple pie charts for showing proportions.

pie title Browser Market Share (2026)
    "Chrome" : 65
    "Safari" : 18
    "Firefox" : 8
    "Edge" : 5
    "Other" : 4

Mindmaps

Mindmaps use indentation to define hierarchy — no arrows needed.

mindmap
    root((Web Development))
        Frontend
            HTML
            CSS
            JavaScript
                React
                Vue
                Svelte
        Backend
            Node.js
            Python
            Go
        Database
            PostgreSQL
            MongoDB
            Redis

State Diagrams

Model state machines with transitions and conditions.

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Approved : approve
    Review --> Draft : request changes
    Approved --> Published : publish
    Published --> [*]

Quick Reference Table

Try It Yourself

Have an existing diagram you want to convert? Upload a screenshot and get editable Mermaid code in seconds. Try ImageToMermaid free.