All Mermaid.js Diagram Types Explained (With Examples)

What Diagram Types Does Mermaid.js Support?

Mermaid.js is not just a flowchart tool. As of 2026, it supports 13+ distinct diagram types — covering everything from database schemas and git history to user journeys and data flows. Each type has its own syntax, use cases, and strengths.

This guide walks through every major Mermaid diagram type with a quick example and a summary of when to use it.

1. Flowchart

The most-used diagram type. Flowcharts visualize processes, decision trees, and system flows. Mermaid supports four layout directions: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left).

flowchart LR
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Process --> Output([Done])
    Error --> Input

Best for: Process flows, decision trees, architecture overviews, user flows, CI/CD pipelines.

2. Sequence Diagram

Shows interactions between actors over time — who sends what message to whom, in what order.

sequenceDiagram
    autonumber
    actor User
    participant API
    participant DB

    User->>API: POST /login
    API->>DB: SELECT user WHERE email=?
    DB-->>API: User record
    API-->>User: 200 OK + JWT token

Best for: API call flows, authentication sequences, microservice communication, protocol documentation.

3. Class Diagram

Represents object-oriented structures: classes, attributes, methods, and their relationships (inheritance, composition, association).

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

Best for: OOP design documentation, code architecture, domain modeling, API object schemas.

4. Entity Relationship (ER) Diagram

Documents database schemas — tables, columns, data types, and relationships with cardinality.

erDiagram
    USER {
        int id PK
        string email UK
        string name
    }
    POST {
        int id PK
        string title
        int user_id FK
    }
    COMMENT {
        int id PK
        text body
        int post_id FK
        int user_id FK
    }
    USER ||--o{ POST : writes
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes

Best for: Database design, schema documentation, data modeling, migration planning.

5. Gantt Chart

Project timeline visualization — tasks, durations, milestones, and dependencies.

gantt
    title Project Roadmap Q3 2026
    dateFormat YYYY-MM-DD
    section Backend
        API design       :done,    a1, 2026-07-01, 7d
        DB schema        :done,    a2, after a1, 5d
        Core endpoints   :active,  a3, after a2, 14d
    section Frontend
        UI components    :         b1, 2026-07-10, 10d
        Integration      :         b2, after b1, 7d
    section Launch
        QA testing       :         c1, after a3, 5d
        Deploy           :milestone, c2, after c1, 0d

Best for: Project planning, sprint tracking, roadmaps, release timelines.

6. State Diagram

Models finite state machines — the states an entity can be in and the transitions between them.

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : submit
    Processing --> Success : result OK
    Processing --> Failed : result error
    Failed --> Idle : retry
    Success --> [*]

Best for: UI state machines, order lifecycles, session states, workflow engines, protocol modeling.

7. Mindmap

Hierarchical branching structure for brainstorming and knowledge organization.

mindmap
  root((Mermaid.js))
    Diagrams
      Flowchart
      Sequence
      Class
      ER
    Integrations
      GitHub
      Notion
      VS Code
      Obsidian
    Features
      Themes
      Dark mode
      Click events

Best for: Brainstorming, knowledge maps, feature breakdowns, study notes.

8. Timeline

Displays events along a chronological axis, grouped by time periods.

timeline
    title History of JavaScript Frameworks
    2010 : Backbone.js
         : AngularJS
    2013 : React
    2014 : Vue.js
    2016 : Angular 2
    2019 : Svelte 3
    2022 : SolidJS gains traction
    2024 : React Server Components mainstream

Best for: Historical timelines, product roadmaps, release histories, organizational milestones.

9. Pie Chart

Simple proportional visualization — how parts make up a whole.

pie title Browser Market Share 2026
    "Chrome" : 63
    "Safari" : 20
    "Firefox" : 7
    "Edge" : 6
    "Other" : 4

Best for: Distribution breakdowns, budget allocations, survey results, technology share snapshots. Keep slices to 5–7 max.

10. Quadrant Chart

Plots items on a 2×2 grid based on two axes — great for prioritization matrices.

quadrantChart
    title Feature Prioritization Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Plan
    quadrant-3 Delegate
    quadrant-4 Deprioritize
    Auth Redesign: [0.3, 0.8]
    Dark Mode: [0.2, 0.5]
    Dashboard V2: [0.7, 0.9]
    Export PDF: [0.6, 0.4]
    Onboarding Tour: [0.4, 0.7]

Best for: Feature prioritization, tech debt triage, risk assessment, 2×2 strategy matrices.

11. Git Graph

Visualizes git branch history — commits, branches, merges, and tags.

gitGraph
    commit id: "init"
    branch develop
    checkout develop
    commit id: "feature A"
    commit id: "feature B"
    branch feature/login
    commit id: "login UI"
    commit id: "auth API"
    checkout develop
    merge feature/login
    checkout main
    merge develop tag: "v1.0"

Best for: Documenting branching strategies (GitFlow, trunk-based), explaining merge workflows, teaching Git concepts.

12. C4 Architecture Diagram

Structured system architecture at four levels: Context, Container, Component, and Code.

C4Context
    title System Context — E-Commerce Platform
    Person(customer, "Customer", "Shops online")
    System(shop, "E-Commerce App", "Product catalog, cart, checkout")
    System_Ext(payment, "Payment Gateway", "Stripe / Razorpay")
    System_Ext(email, "Email Service", "Order confirmations")
    Rel(customer, shop, "Browses and purchases")
    Rel(shop, payment, "Processes payments")
    Rel(shop, email, "Sends confirmations")

Best for: Enterprise architecture documentation, solution design, onboarding new engineers, stakeholder presentations.

13. Sankey Diagram

Shows flows and quantities between nodes — budget allocations, data pipelines, energy flows.

sankey-beta
    Revenue,Product Sales,600
    Revenue,Services,300
    Revenue,Licensing,100
    Product Sales,COGS,250
    Product Sales,Gross Profit,350
    Services,Delivery Cost,120
    Services,Gross Profit,180
    Licensing,Gross Profit,100

Best for: Financial flows, energy systems, budget waterfall analysis, traffic source breakdowns.

14. XY Chart

Bar and line charts for numeric data visualization directly in documentation.

xychart-beta
    title "Monthly Active Users 2026"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Users (thousands)" 0 --> 100
    bar [28, 35, 42, 55, 68, 80]
    line [28, 35, 42, 55, 68, 80]

Best for: Metrics dashboards in docs, growth charts, performance benchmarks, A/B test results.

Choosing the Right Diagram Type

Tips for Picking the Right Diagram

1. Match the question, not the data. Every diagram type answers a specific question. Start with "What am I trying to communicate?" — the right type becomes obvious.

1. Start simple. A flowchart with 5 nodes beats a sprawling C4 diagram with 40 boxes when you're explaining a quick concept.

1. Use multiple types together. A README might have a C4 context diagram for the overview, an ER diagram for the data model, and a sequence diagram for a key API flow. They complement each other.

1. Version-control them all. Because Mermaid is text, every diagram lives in your repo alongside the code it documents. Change the code, update the diagram in the same PR.

1. Test in a live editor first. Before embedding a diagram in docs, prototype it in a live Mermaid editor to catch syntax errors and refine the layout.

Conclusion

Mermaid.js gives developers a single text-based toolkit for 14+ diagram types — from simple flowcharts to full C4 architecture models. Learning which diagram type fits each situation is the real skill. Use this guide as your reference, and start prototyping your next diagram in the editor below.

Try every diagram type in our free Mermaid editor →