Mermaid Diagrams: Flowcharts, Sequence Diagrams & Diagram-as-Code Guide

What is Mermaid?

Mermaid is a JavaScript-based diagramming tool that uses a simple text syntax to generate diagrams. You write code; Mermaid renders flowcharts, sequence diagrams, UML class diagrams, entity-relationship diagrams, Gantt charts, pie charts, mind maps, and Git graphs. Because the source is text, diagrams are version-control friendly, easy to diff, and can be embedded in Markdown (e.g. ```mermaid ... ```) on GitHub, GitLab, and many static site generators.

Why Use Mermaid for Diagrams?

Text-based diagrams are easier to maintain than static images and integrate naturally into developer workflows:

Mermaid Diagram Types with Examples

Mermaid supports many diagram types. Each example below can be pasted into our Mermaid Editor for a live preview.

1. Flowcharts

Flowcharts are ideal for process flows, decision trees, and algorithms. Use flowchart TD (top-down) or flowchart LR (left-right). Node shapes: [] rectangles, diamonds for decisions, () rounded for start/end.

flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action 1]
  B -->|No| D[Action 2]
  C --> E[End]
  D --> E

Use cases: Process documentation, algorithm visualization, decision trees, user flows.

2. Sequence Diagrams

Sequence diagrams show interactions between participants over time—perfect for API calls, microservice communication, or user-to-system flows.

sequenceDiagram
  participant User
  participant API
  participant Database

  User->>API: Request Data
  API->>Database: Query
  Database-->>API: Results
  API-->>User: Response

Use cases: API documentation, system communication, user flows, request/response flows.

3. Class Diagrams

Class diagrams visualize object-oriented structure: classes, attributes, methods, and relationships (inheritance, composition).

classDiagram
  class User {
      +String name
      +String email
      +login()
      +logout()
  }
  class Admin {
      +manageUsers()
  }
  User <|-- Admin

Use cases: Software architecture, OOP design, API model documentation.

4. State Diagrams

State diagrams model state machines: states and transitions. Use stateDiagram-v2 for the modern syntax.

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing: Start
  Processing --> Completed: Success
  Processing --> Error: Failure
  Completed --> [*]
  Error --> Idle: Retry

Use cases: Workflow states, process states, UI or backend state machines.

5. ER Diagrams

Entity-relationship diagrams describe database schemas: entities, attributes, and relationships (one-to-many, many-to-many).

erDiagram
  USER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : "ordered in"

  USER {
      string id PK
      string name
      string email
  }
  ORDER {
      string id PK
      datetime created_at
  }

Use cases: Database design, data modeling, schema documentation.

6. Gantt Charts

Gantt charts show project timelines with tasks, dates, and dependencies. Use after to chain tasks.

gantt
  title Project Timeline
  dateFormat YYYY-MM-DD
  section Phase 1
  Planning    :a1, 2024-01-01, 7d
  Design      :a2, after a1, 10d
  section Phase 2
  Development :b1, after a2, 14d
  Testing     :b2, after b1, 7d

Use cases: Project planning, sprint timelines, milestone tracking.

7. Pie Charts, Mind Maps & Git Graphs

Mermaid also supports pie (data distribution), mindmap (ideas and categories), and gitGraph (branch and commit visualization). Syntax varies; check the official mermaid.js.org docs or the Quick Reference in our tool.

Using Our Mermaid Editor (Step by Step)

Our Mermaid Diagram Editor runs entirely in your browser. No sign-up; your diagrams never leave your device.

Mermaid Syntax Quick Reference

Handy reference for flowcharts and common patterns. For full syntax, see mermaid.js.org.

Best Practices for Mermaid Diagrams

Keep diagrams maintainable and readable:

Common Pitfalls & How to Avoid Them

Avoid these Mermaid mistakes:

Pro Tips

Get more from Mermaid and our editor: