Mermaid Flowchart Complete Guide: From Basics to Advanced Styling

Flowcharts are the most widely used diagram type in technical documentation, project management, and system design. They transform complex processes into visual, easy-to-follow maps. Mermaid makes creating these diagrams incredibly efficient by letting you define them entirely in code.

This guide covers everything you need to know about Mermaid flowcharts—from basic syntax to advanced customization techniques.

Why Use Mermaid for Flowcharts?

Traditional diagramming tools require clicking, dragging, and manual alignment. Mermaid eliminates this friction entirely.

• Version control friendly: Your diagrams live as text in Git, enabling diff tracking and code review.
• Rapid iteration: Changing a label or adding a step takes seconds, not minutes.
• Automation ready: Generate diagrams from data or CI pipelines without a GUI.
• Universal compatibility: Rendered natively on GitHub, GitLab, Notion, and many documentation platforms.

Understanding Flowchart Directions

Every Mermaid flowchart starts with the graph keyword followed by a direction specifier.

graph TD
    A[Start] --> B[Process]
    B --> C[End]

Choosing the right direction significantly impacts readability. Vertical layouts work well for sequential steps, while horizontal layouts excel at showing parallel workflows or system boundaries.

Node Shapes and Their Meanings

Mermaid supports over 20 node shapes. Using them semantically makes your diagrams instantly more professional.

Essential Shapes

graph LR
    A[Rectangle] --> B(Rounded)
    B --> C{Decision}
    C --> D((Connection))
    C --> E>Asymmetric]

Advanced Shapes

graph LR
    A[/Parallelogram/] --> B[\Trapezoid\]
    B --> C{{Hexagon}}
    C --> D[(Database)]
    D --> E[/\Double Slash\/]

Semantic Shape Conventions

Following these conventions ensures anyone reading your diagram understands the process flow without needing a legend.

Link Styles and Labels

Links are the backbone of any flowchart. Mermaid provides multiple arrow types and the ability to label connections.

Basic Links

graph LR
    A --> B
    A -.-> C
    A ==> D
    A --- E

Labeled Links

When branches require conditions, add labels to clarify the logic:

graph TD
    A{Is user authenticated?} -->|Yes| B[Show dashboard]
    A -->|No| C[Redirect to login]
    C --> D[Prompt for credentials]
    D --> E{Valid credentials?}
    E -->|Yes| A
    E -->|No| F[Show error message]
    F --> D

Link Style Reference

Organizing with Subgraphs

Complex diagrams become unreadable without structure. Subgraphs let you group related nodes into logical containers.

graph TD
    subgraph Frontend
        A[Login Form] --> B[API Client]
    end

    subgraph Backend
        C[Auth Controller] --> D[(User DB)]
        C --> E[JWT Service]
    end

    subgraph External
        F[Email Provider]
    end

    B --> C
    E --> F

Subgraphs are invaluable for:

• System architecture diagrams: Separate frontend, backend, and external services.
• Team handoffs: Show where one team's responsibility ends and another begins.
• Security boundaries: Visualize trust zones and network segments.

Custom Styling with CSS

Mermaid allows inline style definitions to customize colors, borders, and fonts.

graph TD
    A[Start] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[End]
    D --> E

    style A fill:#4f46e5,stroke:#3730a3,color:#fff
    style B fill:#f59e0b,stroke:#d97706,color:#fff
    style D fill:#ef4444,stroke:#dc2626,color:#fff
    style E fill:#10b981,stroke:#059669,color:#fff

You can also define reusable class styles:

graph LR
    A[Normal Step] --> B[Warning Step]
    B --> C[Error Step]
    B --> D[Success Step]

    classDef default fill:#f3f4f6,stroke:#9ca3af
    classDef warning fill:#fef3c7,stroke:#f59e0b
    classDef error fill:#fee2e2,stroke:#ef4444
    classDef success fill:#d1fae5,stroke:#10b981

    class B warning
    class C error
    class D success

Real-World Example: E-Commerce Checkout

Here is a production-quality flowchart showing a complete checkout process:

graph TD
    A[View Cart] --> B{Cart empty?}
    B -->|Yes| C[Show empty cart message]
    B -->|No| D[Enter shipping info]
    D --> E{Address valid?}
    E -->|No| D
    E -->|Yes| F[Select payment method]
    F --> G[Enter payment details]
    G --> H{Payment approved?}
    H -->|No| I[Show payment error]
    I --> G
    H -->|Yes| J[Create order]
    J --> K[Send confirmation email]
    K --> L[Show order summary]
    C --> M[End]
    L --> M

    style C fill:#fee2e2,stroke:#ef4444
    style L fill:#d1fae5,stroke:#10b981

Best Practices for Professional Flowcharts

1. Keep direction consistent: Mixing TD and LR in the same diagram confuses readers. Use subgraphs if you need different layouts.
2. Limit node count: If a diagram exceeds 15-20 nodes, split it into multiple connected diagrams or use subgraphs aggressively.
3. Label all decision branches: Every diamond should have clearly labeled exits (Yes/No, Pass/Fail, etc.).
4. Use semantic shapes: Readers intuitively understand that diamonds mean decisions and cylinders mean databases.
5. Add styling sparingly: Color should reinforce meaning, not decorate. Reserve red for errors, green for success, and yellow for warnings.
6. Validate your syntax: Mermaid2img provides real-time error checking. Use it to catch syntax issues before embedding diagrams in documentation.

Conclusion

Mermaid flowcharts strike the perfect balance between simplicity and power. With just a few lines of text, you can create diagrams that would take significantly longer in traditional GUI tools. By mastering directions, shapes, links, subgraphs, and styling, you will be able to communicate complex processes with clarity and professionalism.

Ready to create your own? Open Mermaid2img, paste your flowchart code, and export it as a high-resolution PNG or scalable SVG in seconds.