Mermaid Diagram Types: Which One to Use, with a Tiny Example of Each

A Mermaid diagram type is the kind of chart the code draws, and it is set by the keyword on the first line: flowchart, sequenceDiagram, gantt and so on. Mermaid's documentation lists more than 30 types as of version 12.1 (October 2026). The 13 below cover processes, systems, plans and simple numbers. Each has a one-line use case and an example small enough to paste into any Mermaid renderer; every example here was checked against Mermaid 12.1.

Which Mermaid diagram type should you use?

Which types show processes and conversations?

Flowchart

Boxes and arrows for any process or decision. LR lays it out left to right; TD top to bottom. Curly brackets make a decision diamond.

flowchart LR
    A[Brief] --> B[Draft] --> C{Approved?}
    C -->|Yes| D[Publish]
    C -->|No| B

Sequence diagram

Who sends what to whom, in time order: ordering flows, logins, approvals. ->> is a message, -->> a reply.

sequenceDiagram
    participant Customer
    participant Shop
    Customer->>Shop: Place order
    Shop-->>Customer: Confirmation email

State diagram

The stages one thing passes through, such as a document or an order. [*] marks the start and the finish.

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

User journey

Steps a customer takes, grouped into sections, each scored from 1 to 5 for how the step feels.

journey
    title Buying a coffee online
    section Find
      Search for a cafe: 4: Customer
    section Order
      Choose a drink: 5: Customer
      Pay: 2: Customer

Which types show structures and systems?

Class diagram

Things, their details and how they relate. Developers use it for code; it also works for any "what has what" model.

classDiagram
    class Customer {
        +String name
        +placeOrder()
    }
    class Order {
        +Date date
    }
    Customer "1" --> "*" Order : places

Entity relationship (ER) diagram

Tables in a database and how they link. ||--o{ reads "one to zero or more".

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains

Mindmap

A central idea with branches. There are no arrows: indentation sets the levels, and there can be only one item at the top level.

mindmap
  root((Product launch))
    Marketing
      Email
      Social posts
    Sales
      Demo script

Git graph

Branches, commits and merges in a code repository, useful for explaining a team's branching rules.

gitGraph
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature

Which types show plans and dates?

Gantt chart

Tasks as bars on a calendar, with dependencies (after a1) and milestones. Dates must match the dateFormat line.

gantt
    title Website relaunch
    dateFormat YYYY-MM-DD
    section Plan
    Brief and sitemap :a1, 2026-11-02, 5d
    section Build
    Design :a2, after a1, 10d
    Development :a3, after a2, 15d
    Launch :milestone, after a3, 0d

Timeline

Events in order without exact dates or durations: a company history, a product's releases, a year in review.

timeline
    title Company history
    2019 : Founded
    2021 : First 100 customers
    2024 : Opened a London office

Which types show numbers?

Pie chart

Shares of a whole. Labels go in double quotes, and the docs say values must be positive numbers.

pie title Where the budget goes
    "Ads" : 45
    "Content" : 30
    "Tools" : 25

Quadrant chart

Items plotted on two scales, such as effort against impact. Each point takes x and y values between 0 and 1.

quadrantChart
    title Which tasks to do first
    x-axis Low effort --> High effort
    y-axis Low impact --> High impact
    quadrant-1 Plan carefully
    quadrant-2 Do first
    quadrant-3 Fill-ins
    quadrant-4 Skip
    New homepage: [0.8, 0.9]
    Fix typos: [0.2, 0.3]

XY chart

Simple bar and line charts. Text with spaces goes in double quotes.

xychart-beta
    title "Monthly sign-ups"
    x-axis [Jan, Feb, Mar, Apr]
    y-axis "Sign-ups" 0 --> 500
    bar [120, 210, 340, 460]

Which diagram types are still experimental?

The mindmap and timeline pages are still headed "experimental": "The syntax and properties can change in future releases." Both add that the syntax is stable except for icons, so ordinary diagrams like the ones above are safe to use.

The XY chart has graduated. Mermaid 11.10.0 removed the -beta suffix from the XY chart, block and Sankey diagrams "to reflect their stable status", so newer versions accept plain xychart. The old xychart-beta keyword still works in Mermaid 12.1, and apps running an older Mermaid only understand that form, which is why the example above uses it. If code renders in one app and fails in another, a version gap like this is a likely cause; the guide to Mermaid syntax errors covers the other usual suspects.

How do you turn any of these into an image?

Every type here renders the same way: paste the code into a Mermaid renderer and download the result. The free Mermaid Live Editor exports one diagram at a time as a PNG or SVG. Renda's Mermaid to PNG recognises all 13 types from their first line, finds every diagram in a pasted ChatGPT or Claude reply, and renders each one as a PNG at 2x its own size, at a slide or social size, or as a PDF. Five PNGs a month are free. If you would rather have an AI write the code, the AI flowchart maker guide has prompts for flowcharts, org charts, journeys, decision trees and Gantt charts.

Frequently asked questions