Mermaid Cheat Sheet

Start here: the only three rules

A Mermaid diagram is just text that follows three rules. Learn these and every diagram type becomes a matter of looking up vocabulary.

Line one names the diagram type. For example flowchart LR or sequenceDiagram. Get this wrong and nothing renders.
One statement per line. Each line describes a single box, arrow, or message.
Indent the body. Indentation is for readability, but keep it consistent — two or four spaces for every line under the first.

Here is the smallest useful diagram. A and B are short IDs you invent, and the text in brackets is the label a reader sees.

flowchart LR
    A[Order placed] --> B[Order shipped]

Not sure which diagram to use? Use a flowchart for steps and decisions, a sequence diagram for who talks to whom over time, a class or ER diagram for how data is structured, and a gantt chart for schedules.

Flowcharts: steps and decisions

Flowcharts are the workhorse. After flowchart you add a direction: LR (left to right), TD or TB (top down), RL, or BT.

Shapes, decisions and labelled arrows

The bracket style around a label decides the shape. Text between pipes on an arrow, like -->|Yes|, labels that arrow — perfect for the branches of a decision.

flowchart TD
    Start([Customer arrives]) --> Ask[/Take the order/]
    Ask --> Check{In stock?}
    Check -->|Yes| Cook[Prepare the food]
    Check -->|No| Sorry[Offer an alternative]
    Cook --> Pay[(Take payment)]
    Pay --> Done([Hand over the order])
    Sorry --> Ask

Grouping and highlighting

Wrap related steps in a subgraph to show a boundary such as a team, system, or building. classDef defines a colour, and class applies it to specific nodes.

flowchart LR
    classDef warm fill:#fff2d5,stroke:#cfad52

    subgraph Store[Inside the store]
        Counter[Front counter] --> Grill[Grill station]
        Grill --> Wrap[Wrapping station]
    end

    Customer[Customer] --> Counter
    Wrap --> Customer
    class Grill,Wrap warm

Sequence diagrams: who talks to whom

Sequence diagrams read top to bottom as time passes. Each participant gets a vertical line, and every message is an arrow between two lines. Use participant for systems and actor for people; as gives a short ID a friendly label.

Messages, replies and notes

->> is a request (solid arrow) and -->> is a reply (dashed arrow). autonumber numbers the steps for you, and notes let you explain something without inventing a fake message.

sequenceDiagram
    autonumber
    actor C as Customer
    participant K as Cashier
    participant G as Kitchen

    C->>K: Order a burger meal
    Note right of K: Payment happens before cooking
    K->>C: Ask for payment
    C->>K: Pay
    K->>G: Send order to kitchen
    G-->>K: Burger is ready
    K-->>C: Hand over the meal

Alternatives, loops and self-messages

Blocks let you show branching. alt and else cover two outcomes, opt covers something that may not happen, and loop covers repetition. Every block must end with end. An arrow from a participant to itself shows internal work.

sequenceDiagram
    actor C as Customer
    participant K as Kiosk
    participant P as Payment provider

    C->>K: Choose a meal
    K->>K: Calculate total
    K->>P: Request payment
    alt Card approved
        P-->>K: Approved
        K-->>C: Print receipt
    else Card declined
        P-->>K: Declined
        loop Up to 3 attempts
            K-->>C: Ask for another card
        end
    end
    opt Customer wants a bag
        K-->>C: Add a bag
    end

Class, state and data diagrams

State diagram: what something can be doing

Use [*] for the start and end points, and --> with a colon to label what causes each change.

stateDiagram-v2
    [*] --> Placed
    Placed --> Cooking : payment received
    Cooking --> Ready : food finished
    Ready --> Collected : handed to customer
    Collected --> [*]
    Placed --> Cancelled : customer leaves
    Cancelled --> [*]

Class diagram: objects and their relationships

List fields and methods inside the braces. <|-- means "inherits from" and --> means "uses"; the quoted numbers describe how many of each.

classDiagram
    class Order {
        +String id
        +Date placedAt
        +total() float
    }
    class MealOrder {
        +boolean upsized
    }
    class Item {
        +String name
        +float price
    }
    Order <|-- MealOrder
    Order "1" --> "many" Item : contains

Entity relationship diagram: database tables

The symbols on each side of the line describe quantity: || is exactly one, o{ is zero or more, and |{ is one or more.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "appears in"

    CUSTOMER {
        int id
        string name
    }
    ORDER {
        int id
        datetime placed_at
    }

Plans and summaries

Gantt chart: schedules

Give each task a duration such as 5d or 2w. after chains a task to the end of another one, so you rarely need to type dates twice.

gantt
    title New store opening
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Preparation
    Hire staff        :hire, 2026-01-05, 10d
    Train staff       :after hire, 7d

    section Launch
    Soft opening      :milestone, 2026-02-02, 0d
    Grand opening     :2026-02-09, 3d

Pie chart: proportions

A label in quotes, then a colon, then the number. Mermaid works out the percentages.

pie title Orders by channel
    "Front counter" : 45
    "Self-service kiosk" : 30
    "Mobile app" : 18
    "Delivery partner" : 7

Mind map: brainstorming

Indentation alone creates the hierarchy — no arrows required. Handy for early thinking before you commit to a flowchart.

mindmap
    root((Burger order))
        Food
            Burger
            Fries
        Drink
            Soda
            Coffee
        Extras
            Sauce
            Bag

User journey: how each step feels

Score each step from 1 to 5, then list who is involved. Useful for showing where an experience is painful.

journey
    title Ordering a burger
    section At the counter
        Read the menu: 4: Customer
        Place the order: 3: Customer, Cashier
        Wait for food: 2: Customer
    section Leaving
        Collect order: 5: Customer, Cashier

Quick reference

Flowchart node shapes

Write this	You get
A[Text]	Rectangle — a normal step
A(Text)	Rounded rectangle — softer step
A([Text])	Stadium — start or end point
A{Text}	Diamond — a decision with branches
A[(Text)]	Cylinder — a database or store
A((Text))	Circle — a connector or event
A[/Text/]	Parallelogram — input or output
A[[Text]]	Subroutine — a step defined elsewhere

Flowchart arrows

Write this	You get
A --> B	Solid arrow — normal flow
A --- B	Solid line, no arrowhead — plain link
A -.-> B	Dotted arrow — optional or indirect
A ==> B	Thick arrow — the main path
A -->\|Yes\| B	Labelled arrow — the condition
A --x B	Arrow ending in a cross — blocked or rejected

Sequence diagram arrows and keywords

Write this	You get
A->>B: Text	Solid arrow — a request or action
A-->>B: Text	Dashed arrow — a reply
A-x B: Text	Arrow with a cross — a failure
A->>A: Text	Self-message — internal work
Note over A,B: Text	Note spanning two participants
alt / else / end	Two or more alternative outcomes
opt / end	Something that may not happen
loop Text / end	Repeated steps
par / and / end	Steps happening at the same time
autonumber	Numbers every message automatically

Diagram types at a glance

First line	Use it for
flowchart LR	Steps, decisions, processes
sequenceDiagram	Conversations between people or systems over time
stateDiagram-v2	The states something moves through
classDiagram	Objects, their fields, and relationships
erDiagram	Database tables and how they relate
gantt	Schedules and timelines
pie	Proportions of a whole
mindmap	Brainstorming and grouping ideas
journey	How each step of an experience feels

When it breaks

Almost every Mermaid error comes from one of a handful of mistakes. Work down this list before rewriting anything.

Check the first line. A typo in sequenceDiagram or a missing direction after flowchart stops everything.
Count your end keywords. Every alt, opt, loop, par, and subgraph needs exactly one.
Quote awkward labels. If a label contains brackets, colons, or punctuation that confuses the parser, wrap it in quotes: A["Total (with tax)"].
Don't mix diagram types. Sequence keywords will not work inside a flowchart, and the other way around.
Keep IDs simple. Use short names without spaces for IDs, and put the human wording in the label.
Add line breaks with <br> inside a label rather than pressing Enter, which would start a new statement.

Build diagrams a few lines at a time and render often. When something breaks you will know exactly which line caused it, and the renderer shows Mermaid's own error message underneath.