Mermaid.js Flowchart Styling: Colors, Classes & Custom Themes

# Mermaid.js Flowchart Styling: Colors, Classes & Custom Themes

Mermaid.js flowcharts look decent out of the box, but real-world documentation demands custom styling — branded colors, highlighted paths, status indicators, and readable layouts. This guide covers every styling technique available in Mermaid.js flowcharts, from inline styles to reusable CSS classes and full theme customization.

Why Style Your Mermaid Flowcharts?

Default Mermaid diagrams use a generic color palette. Custom styling helps you:

• Highlight critical paths in workflows
• Match brand guidelines in documentation
• Indicate status (success, failure, pending) with color coding
• Improve readability for complex diagrams
• Create professional documentation that stands out

Inline Styles with `style` Keyword

The simplest way to style individual nodes is the style keyword. Apply it after defining your flowchart:

flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
    style A fill:#4CAF50,stroke:#333,stroke-width:2px,color:#fff
    style B fill:#2196F3,stroke:#333,stroke-width:2px,color:#fff
    style C fill:#f44336,stroke:#333,stroke-width:2px,color:#fff

Available style properties:

Reusable Styles with `classDef`

For diagrams with many nodes, inline styles get repetitive. Use classDef to define reusable style classes, then apply them with :::className or the class keyword:

flowchart TD
    A[Deploy to Staging]:::success --> B{Tests Pass?}
    B -->|Yes| C[Deploy to Prod]:::success
    B -->|No| D[Rollback]:::danger
    D --> E[Fix & Retry]:::warning
    E --> A

    classDef success fill:#4CAF50,stroke:#2E7D32,color:#fff
    classDef danger fill:#f44336,stroke:#c62828,color:#fff
    classDef warning fill:#FF9800,stroke:#E65100,color:#fff

You can also assign classes to multiple nodes at once:

flowchart LR
    A[Step 1] --> B[Step 2] --> C[Step 3]
    D[Step 4] --> E[Step 5]

    class A,B,C active
    class D,E inactive

    classDef active fill:#1a73e8,stroke:#174ea6,color:#fff
    classDef inactive fill:#e8eaed,stroke:#9aa0a6,color:#5f6368

Styling Links (Edges)

You can style the connections between nodes using linkStyle. Links are zero-indexed in the order they appear:

flowchart LR
    A --> B --> C --> D

    linkStyle 0 stroke:#f44336,stroke-width:3px
    linkStyle 1 stroke:#4CAF50,stroke-width:3px
    linkStyle 2 stroke:#2196F3,stroke-width:3px,stroke-dasharray:5 5

To style all links at once:

flowchart LR
    A --> B --> C
    linkStyle default stroke:#999,stroke-width:2px

Real-World Example: Styled Architecture Diagram

Here is a practical example showing a microservices architecture with color-coded layers:

flowchart TB
    subgraph Client Layer
        A[Web App]:::frontend
        B[Mobile App]:::frontend
    end

    subgraph API Layer
        C[API Gateway]:::api
        D[Auth Service]:::api
    end

    subgraph Services
        E[User Service]:::service
        F[Order Service]:::service
        G[Payment Service]:::service
    end

    subgraph Data Layer
        H[(PostgreSQL)]:::database
        I[(Redis Cache)]:::cache
    end

    A & B --> C
    C --> D
    C --> E & F & G
    E & F --> H
    G --> H
    C --> I

    classDef frontend fill:#42A5F5,stroke:#1565C0,color:#fff
    classDef api fill:#66BB6A,stroke:#2E7D32,color:#fff
    classDef service fill:#FFA726,stroke:#E65100,color:#fff
    classDef database fill:#AB47BC,stroke:#6A1B9A,color:#fff
    classDef cache fill:#EF5350,stroke:#C62828,color:#fff

This pattern makes complex architectures instantly readable by separating concerns visually.

Subgraph Styling

You can also style subgraphs to create visual groupings:

flowchart TB
    subgraph production["Production Environment"]
        A[Load Balancer] --> B[App Server 1]
        A --> C[App Server 2]
    end

    subgraph staging["Staging Environment"]
        D[Staging Server]
    end

    D -->|promote| A

    style production fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px
    style staging fill:#FFF3E0,stroke:#FF9800,stroke-width:2px

Theme Configuration with `init`

For global styling across the entire diagram, use the init directive to configure the theme:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1a73e8', 'primaryTextColor': '#fff', 'primaryBorderColor': '#174ea6', 'lineColor': '#5f6368', 'secondaryColor': '#e8f0fe', 'tertiaryColor': '#f1f3f4'}}}%%
flowchart TD
    A[Start] --> B[Process 1]
    B --> C[Process 2]
    C --> D[End]

Built-in themes you can use:

• default — Standard Mermaid colors
• dark — Dark background with light text
• forest — Green-themed
• neutral — Grayscale, great for printing
• base — Minimal, best for custom themeVariables

Tips for Better Styled Diagrams

1. Limit your palette — Use 3-5 colors maximum. Too many colors create visual noise.
2. Use semantic colors — Green for success, red for errors, blue for information. Your readers already know these conventions.
3. Style subgraphs with soft fills — Use light background colors (#E8F5E9) for subgraphs so node colors remain prominent.
4. Consistent stroke widths — Pick one stroke width and stick with it unless highlighting specific paths.
5. Test in dark mode — If your docs support dark mode, verify your color choices work on both backgrounds.

Try It in the Mermaid Editor

Experimenting with styles is easiest in a live editor. Head over to Mermaid Editor to paste any of these examples, tweak the colors, and see instant results. The live preview makes it simple to fine-tune your palette before embedding diagrams in your documentation.

Conclusion

Mermaid.js flowchart styling transforms basic diagrams into professional, readable documentation. Start with classDef for reusable styles, use linkStyle for edge customization, and leverage themes for global consistency. Whether you are documenting CI/CD pipelines, microservices, or business workflows, proper styling makes your diagrams significantly more effective.