Skip to main content
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:
The default theme with a clean, professional appearance.Best for: General purpose diagrams, documentation, presentations.
The base theme is the only theme that can be customized using theme variables. All other themes have fixed color schemes.

​
Setting themes

Set a theme for all diagrams when initializing Mermaid:
import mermaid from 'mermaid';

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

​
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

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: 
themeVariables: {
  // Node styling
  nodeBorder: '#9370DB',
  nodeTextColor: '#333',
  
  // Cluster/subgraph styling  
  clusterBkg: '#f0fff0',
  clusterBorder: '#9370DB',
  
  // Links
  defaultLinkColor: '#333',
  
  // Edge labels
  edgeLabelBackground: '#e8e8e8',
  
  // Title
  titleColor: '#333'
}

​
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

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'
  }
});

​
Theme reference tables

​
Core variables

VariableDefaultDescription
darkModefalseAffects how derived colors are calculated
background#f4f4f4Background color for calculations
primaryColor#fff4ddPrimary node fill color
primaryTextColorcalculatedText color in primary nodes
primaryBorderColorcalculatedBorder color for primary nodes
secondaryColorcalculatedSecondary element color
secondaryTextColorcalculatedText in secondary elements
secondaryBorderColorcalculatedBorder for secondary elements
tertiaryColorcalculatedTertiary element color
tertiaryTextColorcalculatedText in tertiary elements
tertiaryBorderColorcalculatedBorder for tertiary elements
lineColorcalculatedLine and connector color
textColorcalculatedGeneral text color
fontFamilytrebuchet ms, verdana, arialFont family
fontSize16pxFont size

​
Note variables

VariableDefaultDescription
noteBkgColor#fff5adNote background color
noteTextColor#333Text in notes
noteBorderColorcalculatedNote 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

  • 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()
  • 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
  • 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

Build docs developers (and LLMs) love

Get started for freeTalk to us