The Complete Guide to Mermaid Diagram Types (And When to Use Each One)

Not all diagrams are created equal.

Use the wrong type, and you'll confuse more than you clarify. Use the right one, and complex ideas become instantly clear.

Here's my battle-tested guide to choosing the right diagram.

Flowchart — The Swiss Army Knife

Use when: You need to show a process, workflow, or decision tree.

Flowcharts are the most versatile diagram type. If you're not sure what to use, start here.

flowchart TD
    Start --> Decision
    Decision -->|Yes| Done
    Decision -->|No| TryAgain
    TryAgain --> Decision

Sequence Diagram — The Conversation Mapper

Use when: You need to show how different systems or people interact over time.

Perfect for APIs, user flows, or any back-and-forth communication.

sequenceDiagram
    User->>Website: Click Login
    Website->>Server: Verify credentials
    Server-->>Website: Success!
    Website-->>User: Welcome back!

Class Diagram — The Structure Revealer

Use when: You need to show how code or data is organized.

Great for developers explaining object-oriented designs.

Entity Relationship Diagram — The Database Decoder

Use when: You need to show how data tables relate to each other.

Essential for anyone working with databases.

Gantt Chart — The Timeline Tracker

Use when: You need to show project schedules and dependencies.

Perfect for project planning and status updates.

Pie Chart — The Proportion Illustrator

Use when: You need to show how parts make up a whole.

Keep it simple — no more than 5-6 slices.

Mindmap — The Idea Organizer

Use when: You need to brainstorm or organize thoughts hierarchically.

Great for planning sessions and note-taking.

The golden rule

Ask yourself: "What question is this diagram answering?"

• How does the process work? → Flowchart
• Who talks to whom? → Sequence diagram
• How is the data structured? → ERD
• When does each task happen? → Gantt chart

Match the question to the diagram type, and you'll never go wrong.