Customize Mermaid diagram themes and colors for your brand

Mermaid diagrams render with a default theme, but every color, font, and line style can be customized. Whether you're building branded documentation or matching your design system, theming ensures diagrams look like they belong to your product.

Why diagram theming matters

A default Mermaid flowchart looks generic. When it appears in your documentation, marketing site, or internal wiki, it looks borrowed — like it doesn't quite fit. Theming bridges that gap: same diagram syntax, your colors, your fonts, your visual identity.

The best part: theme changes apply everywhere. Update the theme once, and every diagram inherits the new look instantly.

Theme basics with the %%init%% directive

The simplest way to theme a diagram is the %%init%% directive, a YAML block at the top of any diagram:

%%{init: {'theme': 'default'}}%%
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Retry]

Mermaid ships with four built-in themes:

• default — light grey background, blue/green accents
• dark — dark grey background, cyan/magenta accents
• forest — green tones, natural feel
• neutral — minimal, greyscale

%%{init: {'theme': 'forest'}}%%
graph TD
    A[User Login] --> B{Credentials OK?}
    B -->|Yes| C[Grant Access]
    B -->|No| D[Deny Access]

Deep customization with the themeVariables object

For fine-grained control, use themeVariables to override specific colors and fonts. This object supports 50+ properties — here are the most common:

Variable	Controls	Default
primaryColor	Node background	#1f77b4
primaryTextColor	Text in nodes	#fff
primaryBorderColor	Node outline	#1f77b4
lineColor	Connecting lines	#555
secondaryColor	Secondary backgrounds	#006100
tertiaryColor	Tertiary backgrounds	#fff5ad
fontSize	Base font size	16px
fontFamily	Typeface	"trebuchet ms"
notebkgColor	Note backgrounds	#fff5ad

Example: corporate brand colors (dark blue, orange accent, custom font):

%%{init: {
  'theme': 'default',
  'themeVariables': {
    'primaryColor': '#1e3a8a',
    'primaryTextColor': '#fff',
    'primaryBorderColor': '#ea580c',
    'fontFamily': '"Segoe UI", sans-serif',
    'fontSize': '14px',
    'lineColor': '#0f172a'
  }
}}%%
graph LR
    A["Start Process"] --> B["Validate"]
    B --> C["Execute"]
    C --> D["Complete"]
    style A fill:#ea580c,color:#fff
    style D fill:#10b981,color:#fff

Theme variables by diagram type

Different diagram types support different variables. Sequence diagrams have actorBkg, actorBorder, and actorTextColor for participants. State diagrams use stateBkg and stateBorder. Gantt charts support taskBkg, taskBorderColor, critBkg.

For sequence diagrams with custom actor styling:

%%{init: {
  'theme': 'default',
  'themeVariables': {
    'actorBkg': '#1e40af',
    'actorBorder': '#fff',
    'actorTextColor': '#fff',
    'messageAlign': 'center'
  }
}}%%
sequenceDiagram
    participant Client
    participant API
    participant DB
    Client->>+API: POST /users
    API->>+DB: INSERT user
    DB-->>-API: User created
    API-->>-Client: 201 Created

Building a cohesive documentation theme

Don't customize every diagram independently. Instead, define a theme once and apply it everywhere. The MermaidCreator editor lets you set a default theme for your workspace — all new diagrams inherit it, then you override only when the diagram needs something special.

If you're embedding Mermaid in a static site or documentation generator, set the theme at the site level. In a Next.js or React app, wrap your diagram renderer with a theme provider. In Markdown-heavy workflows, keep %%init%% blocks consistent by copy-pasting the same header.

Here's a reusable template for consistent branding:

%%{init: {
  'theme': 'default',
  'themeVariables': {
    'primaryColor': '#YOUR_PRIMARY',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#YOUR_ACCENT',
    'fontFamily': 'YOUR_TYPEFACE',
    'fontSize': '14px',
    'lineColor': '#YOUR_LINES'
  }
}}%%

Copy this block, fill in your brand colors, and paste it into every new diagram. After the first few, muscle memory takes over.

Dark mode and light mode

Modern products support both light and dark themes. Mermaid doesn't automatically detect the system preference, but you can serve two versions by setting the theme via JavaScript:

For light mode: theme: 'default' For dark mode: theme: 'dark' with custom variables

If your site uses a theme switcher, update the Mermaid theme when the user toggles light/dark. The MermaidCreator playground supports this natively.

Testing your theme

The best way to test a theme is to put it on a few diagrams and see how it looks in context. Create a test page with a flowchart, sequence diagram, and state machine — these three cover most diagram types. If they all look good, your theme is solid.

Export a diagram to PNG from the MermaidCreator editor to see how it looks in presentations or printed docs. Colors often shift between screen and print, so check both.

Common theming patterns

Minimal/documentation style:

primaryColor: '#ffffff'
primaryBorderColor: '#000000'
lineColor: '#333333'
fontSize: '13px'

High-contrast/accessibility:

primaryColor: '#000000'
primaryTextColor: '#ffffff'
lineColor: '#000000'
fontSize: '16px'

Vibrant/marketing:

primaryColor: '#ff6b6b'
secondaryColor: '#4ecdc4'
tertiaryColor: '#ffe66d'
lineColor: '#ff6b6b'

Where theming pays off

• Developer documentation — team brand consistency signals professionalism
• Architecture decisions — different colors for different system layers help readers parse complex diagrams faster
• Presentations — slides with on-brand diagrams feel polished
• Blog posts — your visual identity carries across code and diagrams
• Customer-facing portals — white-labeled diagrams in SaaS tools

FAQ

Can I use gradient colors in Mermaid diagrams? No, Mermaid doesn't support gradient fills directly. Use the closest solid color from your palette.

How do I theme only one diagram if most use the default? Set the default theme at the app level (via your renderer's config), then override with %%init%% for the outlier. The inline settings take precedence.

Will my theme look the same on every platform? Mostly. GitHub, Notion, and most platforms that render Mermaid use the official renderer, so themes are consistent. Browser extensions and older rendering pipelines may vary slightly.

Can I export a themed diagram as SVG? Yes. In MermaidCreator, export to SVG and your theme colors embed in the file. When you include it in your docs, it keeps its custom look.

Spend thirty minutes building a theme that matches your brand, then stop thinking about diagram appearance forever. Try theming in the MermaidCreator editor — paste one of the examples above and experiment with colors until it feels like yours.