Theming

Learn how to customize Mermaid diagram appearance using themes, theme variables, and custom CSS.

Mermaid provides a powerful theming system that allows you to customize the appearance of diagrams. You can use built-in themes, customize theme variables, or apply custom CSS for complete control.

Available themes

Mermaid includes five built-in themes:

default

The default theme with a clean, professional appearance.

Best for: General purpose diagrams, documentation, presentations.

dark

A dark theme optimized for dark backgrounds and dark mode interfaces.

Best for: Dark mode applications, reducing eye strain, modern UIs.

forest

A green-themed design with earthy tones.

Best for: Nature-related content, environmental topics, alternative styling.

neutral

A black and white theme perfect for printing.

Best for: Printed documents, black and white publications, high contrast.

base

A minimal theme that serves as the foundation for customization.

Best for: Custom theming via theme variables. This is the only modifiable theme.

The base theme is the only theme that can be customized using theme variables. All other themes have fixed color schemes.

Setting themes

Site-wide (initialize)

Set a theme for all diagrams when initializing Mermaid:

import mermaid from 'mermaid';

mermaid.initialize({
  theme: 'dark'
});

Per-diagram (frontmatter)

Use frontmatter to set the theme for a specific diagram:

Per-diagram (directive)

Use a directive for quick theme changes:

Theme variables

Theme variables allow you to customize colors and styling. This only works with the base theme.

Core theme variables

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    // Dark mode calculation
    darkMode: false,
    
    // Base colors
    primaryColor: '#fff4dd',
    primaryTextColor: '#333',
    primaryBorderColor: '#9370DB',
    
    secondaryColor: '#ffffde',
    secondaryTextColor: '#333',
    secondaryBorderColor: '#66cdaa',
    
    tertiaryColor: '#f0fff0',
    tertiaryTextColor: '#333',
    tertiaryBorderColor: '#9370DB',
    
    // Background and general
    background: '#f4f4f4',
    textColor: '#333',
    lineColor: '#333',
    
    // Fonts
    fontFamily: 'trebuchet ms, verdana, arial, sans-serif',
    fontSize: '16px',
    
    // Notes (sequence diagrams, etc.)
    noteBkgColor: '#fff5ad',
    noteTextColor: '#333',
    noteBorderColor: '#aaaa33'
  }
});

Color calculation

Understanding derived colors

Mermaid automatically calculates many colors from your primary color choices to ensure visual consistency:

• Border colors are derived from their corresponding fill colors
• Text colors are adjusted based on background for readability
• Secondary and tertiary colors can be calculated from the primary color
• darkMode: true changes how colors are derived for better contrast

// Explicitly set colors
themeVariables: {
  primaryColor: '#BB2528',
  primaryTextColor: '#fff',  // Explicit
  primaryBorderColor: '#7C0000'  // Explicit
}

// Or let Mermaid calculate them
themeVariables: {
  primaryColor: '#BB2528'
  // primaryTextColor and primaryBorderColor will be calculated
}

Mermaid only recognizes hex color codes (e.g., #ff0000). Color names (e.g., red) will not work.

Complete example with theme variables

Diagram-specific theme variables

Different diagram types have specific theme variables:

Flowchart

themeVariables: {
  // Node styling
  nodeBorder: '#9370DB',
  nodeTextColor: '#333',
  
  // Cluster/subgraph styling  
  clusterBkg: '#f0fff0',
  clusterBorder: '#9370DB',
  
  // Links
  defaultLinkColor: '#333',
  
  // Edge labels
  edgeLabelBackground: '#e8e8e8',
  
  // Title
  titleColor: '#333'
}

Sequence diagram

themeVariables: {
  // Actors
  actorBkg: '#ececff',
  actorBorder: '#9370DB',
  actorTextColor: '#333',
  actorLineColor: '#9370DB',
  
  // Signals/messages
  signalColor: '#333',
  signalTextColor: '#333',
  
  // Label box
  labelBoxBkgColor: '#ececff',
  labelBoxBorderColor: '#9370DB',
  labelTextColor: '#333',
  
  // Loops
  loopTextColor: '#333',
  
  // Activation
  activationBorderColor: '#666',
  activationBkgColor: '#f4f4f4',
  
  // Sequence numbers
  sequenceNumberColor: '#fff'
}

Class diagram

themeVariables: {
  // Class text
  classText: '#333'
}

State diagram

themeVariables: {
  // Label color
  labelColor: '#333',
  
  // Composite states
  altBackground: '#f0fff0'
}

ER diagram

themeVariables: {
  // No specific ER variables currently
  // Uses general theme variables
}

Gantt chart

themeVariables: {
  // Grid
  gridColor: '#e0e0e0',
  
  // Today marker
  todayLineColor: '#db5757',
  
  // Sections
  sectionBkgColor: '#d9d9d9',
  sectionBkgColor2: '#ececec',
  
  // Tasks
  taskBorderColor: '#9370DB',
  taskBkgColor: '#b19cd9',
  taskTextColor: '#333',
  taskTextOutsideColor: '#333',
  taskTextLightColor: '#333',
  
  // Active/done/critical tasks
  activeTaskBorderColor: '#7c0',
  activeTaskBkgColor: '#a3f',
  doneTaskBorderColor: '#690',
  doneTaskBkgColor: '#bfc',
  critBorderColor: '#f88',
  critBkgColor: '#fcc',
  
  // Excluded days
  excludeBkgColor: '#f9f9f9'
}

Pie chart

themeVariables: {
  // Pie slices (pie1-pie12)
  pie1: '#BB2528',
  pie2: '#F8B229',
  pie3: '#006100',
  pie4: '#0066CC',
  pie5: '#9370DB',
  pie6: '#FF6B6B',
  pie7: '#4ECDC4',
  pie8: '#FFE66D',
  pie9: '#A8E6CF',
  pie10: '#FF8B94',
  pie11: '#C7CEEA',
  pie12: '#FFDAC1',
  
  // Title
  pieTitleTextSize: '25px',
  pieTitleTextColor: '#333',
  
  // Section labels
  pieSectionTextSize: '17px',
  pieSectionTextColor: '#333',
  
  // Legend
  pieLegendTextSize: '17px',
  pieLegendTextColor: '#333',
  
  // Stroke
  pieStrokeColor: '#000',
  pieStrokeWidth: '2px',
  pieOuterStrokeWidth: '2px',
  pieOuterStrokeColor: '#000',
  
  // Opacity
  pieOpacity: '0.7'
}

Custom CSS

For advanced customization, you can inject custom CSS:

mermaid.initialize({
  theme: 'base',
  themeCSS: `
    .node rect {
      fill: #f9f;
      stroke: #333;
      stroke-width: 2px;
    }
    .node text {
      font-weight: bold;
    }
    .edgeLabel {
      background-color: #ffe;
    }
  `
});

Custom CSS has the highest specificity and will override theme variables. Use with caution as it may break when Mermaid updates its internal structure.

Dynamic theming

Change themes based on user preferences or system settings:

import mermaid, { updateSiteConfig } from 'mermaid';

// Initialize with default theme
mermaid.initialize({ 
  theme: 'default',
  startOnLoad: false 
});

// Switch theme based on system preference
function applyTheme() {
  const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  
  updateSiteConfig({
    theme: isDark ? 'dark' : 'default'
  });
  
  // Re-render diagrams
  mermaid.run();
}

// Listen for changes
window.matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', applyTheme);

// Apply initial theme
applyTheme();

Theme examples

Corporate brand

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#0066CC',      // Brand blue
    primaryTextColor: '#fff',
    primaryBorderColor: '#004C99',
    secondaryColor: '#00CC66',    // Brand green
    tertiaryColor: '#FFB84D',     // Brand orange
    background: '#FFFFFF',
    fontFamily: 'Helvetica, Arial, sans-serif',
    fontSize: '14px'
  }
});

High contrast

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#000000',
    primaryTextColor: '#FFFFFF',
    primaryBorderColor: '#FFFFFF',
    secondaryColor: '#FFFFFF',
    secondaryTextColor: '#000000',
    secondaryBorderColor: '#000000',
    lineColor: '#000000',
    background: '#FFFFFF',
    textColor: '#000000',
    fontSize: '18px'
  }
});

Pastel

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#FFE4E1',      // Misty rose
    primaryTextColor: '#333',
    primaryBorderColor: '#FFB6C1',
    secondaryColor: '#E0FFFF',    // Light cyan
    secondaryTextColor: '#333',
    tertiaryColor: '#F0E68C',     // Khaki
    background: '#FFF8F8',
    lineColor: '#D8BFD8',         // Thistle
    fontFamily: 'Georgia, serif'
  }
});

Dark blue

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    darkMode: true,
    primaryColor: '#1e3a5f',
    primaryTextColor: '#e0e0e0',
    primaryBorderColor: '#4a90e2',
    secondaryColor: '#2c5aa0',
    tertiaryColor: '#16213e',
    background: '#0f1419',
    textColor: '#e0e0e0',
    lineColor: '#4a90e2'
  }
});

Theme reference tables

Core variables

Variable	Default	Description
darkMode	false	Affects how derived colors are calculated
background	#f4f4f4	Background color for calculations
primaryColor	#fff4dd	Primary node fill color
primaryTextColor	calculated	Text color in primary nodes
primaryBorderColor	calculated	Border color for primary nodes
secondaryColor	calculated	Secondary element color
secondaryTextColor	calculated	Text in secondary elements
secondaryBorderColor	calculated	Border for secondary elements
tertiaryColor	calculated	Tertiary element color
tertiaryTextColor	calculated	Text in tertiary elements
tertiaryBorderColor	calculated	Border for tertiary elements
lineColor	calculated	Line and connector color
textColor	calculated	General text color
fontFamily	trebuchet ms, verdana, arial	Font family
fontSize	16px	Font size

Note variables

Variable	Default	Description
noteBkgColor	#fff5ad	Note background color
noteTextColor	#333	Text in notes
noteBorderColor	calculated	Note border color

Best practices

1. Use the base theme for customization - It’s the only theme designed to be modified
2. Test color contrast - Ensure text is readable against backgrounds
3. Use hex colors only - Color names are not supported
4. Set darkMode appropriately - Helps Mermaid calculate better derived colors
5. Consider accessibility - Follow WCAG guidelines for color contrast
6. Document your theme - Keep a reference of your custom color scheme
7. Test across diagram types - Theme variables affect different diagrams differently

Troubleshooting

Theme changes not applying

• Ensure you’re using the base theme when setting themeVariables
• Check that colors are in hex format (#rrggbb)
• Verify there are no typos in variable names
• Clear any cached configurations with reset()

Poor color contrast

• Set darkMode: true for dark backgrounds
• Explicitly set text colors instead of relying on calculation
• Test with a contrast checker tool
• Use the neutral theme for black and white output

Inconsistent appearance across diagrams

• Some diagram types use different theme variables
• Not all variables apply to all diagram types
• Consider using custom CSS for fine-grained control
• Check diagram-specific theme variable tables

Next steps

Configuration

Explore all configuration options

Syntax overview

Learn Mermaid syntax basics

Diagram types

Explore different diagram types

Examples

See themed diagram examples