Understanding the darkMode Configuration Option in Mermaid: Theme Interaction and Color Recalculation

The darkMode configuration option is a Boolean flag that instructs Mermaid to recalculate derived colors—such as borders, text, and scale palettes—to ensure readability on dark backgrounds, working orthogonally with the selected theme rather than replacing it.

The darkMode configuration option in Mermaid allows developers to optimize diagram rendering for dark canvas surfaces within the mermaid-js/mermaid repository. When enabled, this flag triggers the theming engine to systematically adjust derived color values while preserving the base palette defined by the selected theme. This ensures that diagrams maintain proper contrast and visual balance regardless of whether they appear on light or dark backgrounds.

How darkMode Works Under the Hood

Color Recalculation in the Theme Base Class

According to the Mermaid source code, the central logic for darkMode resides in packages/mermaid/src/themes/theme-base.js. The common Theme base class consults this flag during initialization to determine appropriate color values for text, borders, and backgrounds.

// packages/mermaid/src/themes/theme-base.js
this.primaryTextColor = this.primaryTextColor || (this.darkMode ? '#eee' : '#333');
this.primaryBorderColor = this.primaryBorderColor || mkBorder(this.primaryColor, this.darkMode);

if (this.darkMode) {
  for (let i = 0; i < this.THEME_COLOR_LIMIT; i++) {
    this['cScale' + i] = darken(this['cScale' + i], 75);
  }
}

When darkMode is true, primary text color defaults to #eee (light gray) to contrast against dark surfaces, rather than #333 (dark gray) used for light backgrounds. The system also adjusts row colors in ER diagrams by darkening the main background (darken(this.mainBkg, 5)) rather than lightening it (lighten(this.mainBkg, 75)), and applies surface shading multipliers of -4 instead of -1 to push surfaces visually deeper.

Border and Scale Adjustments

The mkBorder helper function defined in packages/mermaid/src/themes/theme-helpers.js uses the darkMode flag to calculate appropriate border luminance:

// packages/mermaid/src/themes/theme-helpers.js
export const mkBorder = (col, darkMode) =>
  darkMode ? adjust(col, { s: -40, l: 10 }) : adjust(col, { s: -40, l: -10 });

In dark mode, borders are lightened (l: 10) to remain visible against dark backgrounds, whereas standard mode darkens them (l: -10). Additionally, scale palettes (cScale0 through cScaleN) are darkened by 75% in dark mode compared to only 25% in light mode, ensuring that sequential colors remain distinguishable on dark canvases.

Interaction Between darkMode and Theme Selection

The darkMode option operates orthogonally to the theme property. While theme selects the base color palette (such as default, dark, forest, neutral, or base), darkMode modifies how derived colors are calculated from that palette without altering the fundamental color scheme.

Using darkMode with the Base Theme

The base theme is specifically designed for customization via themeVariables. When combining theme: "base" with darkMode: true, the engine respects your custom color overrides while applying dark-appropriate adjustments to borders and text:

---
config:
  theme: base
  themeVariables:
    darkMode: true
    primaryColor: '#1e3a8a'
    primaryTextColor: '#fffb'
---
graph LR
  A[Start] --> B[Process]
  B --> C[End]

In this configuration, the custom primary color remains intact while the mkBorder function generates appropriately lightened borders, and text defaults to light colors unless explicitly overridden.

Pre-defined Themes and darkMode

Pre-defined themes such as default, forest, and neutral ship with fixed palettes. Enabling darkMode: true on these themes triggers the derived-color logic—adjusting border luminance, text contrast, and scale darkness—while keeping the theme's original base colors. This allows you to use the default theme on a dark website without manually redefining the entire color scheme.

The Dark Theme vs. darkMode Flag

The dark theme is pre-tuned for dark backgrounds with an inherently dark palette. While setting darkMode: true alongside theme: "dark" is valid, it produces nearly identical visual output to using the dark theme alone, as documented in packages/mermaid/src/docs/config/theming.md:

mermaid.initialize({
  theme: 'dark',
  themeVariables: { darkMode: true }
});

Practical Configuration Examples

Enabling Dark Mode on the Default Theme

To render diagrams using the standard color palette but optimized for dark backgrounds:

mermaid.initialize({
  theme: 'default',
  themeVariables: {
    darkMode: true
  }
});

This configuration preserves the default palette while ensuring borders, text, and scale colors provide sufficient contrast against dark surfaces through the recalculation logic in theme-base.js.

Summary

• The darkMode configuration option in Mermaid is a Boolean flag that signals the rendering engine to treat the diagram as appearing on a dark canvas.
• It operates within packages/mermaid/src/themes/theme-base.js by modifying primary text colors, border luminance via the mkBorder helper, and scale palette darkness levels.
• The option functions orthogonally to theme selection: select a theme for the base palette, then apply darkMode to adapt derived colors for dark surfaces.
• When using the base theme, darkMode preserves custom themeVariables while ensuring proper contrast calculations for borders and backgrounds.
• Pre-defined themes like dark already incorporate dark-appropriate base colors, making the darkMode flag redundant but compatible in those configurations.

Frequently Asked Questions

Does darkMode replace the theme property in Mermaid?

No. The darkMode configuration option works alongside the theme property rather than replacing it. While theme determines the base color palette (such as default, forest, or base), darkMode instructs the theming engine in packages/mermaid/src/themes/theme-base.js to recalculate derived colors like borders and text shades to ensure readability on dark backgrounds.

Which source files control the darkMode color calculations?

The primary logic resides in packages/mermaid/src/themes/theme-base.js, where the Theme class checks the darkMode flag to adjust primary text colors, scale palettes via the darken() function, and surface shading multipliers. Border color adjustments are handled by the mkBorder helper in packages/mermaid/src/themes/theme-helpers.js, which uses the flag to determine whether to lighten or darken border luminance.

Can I use darkMode with custom theme variables?

Yes. When using theme: "base", you can combine darkMode: true with custom themeVariables such as primaryColor or primaryTextColor. The system respects your explicit color values while automatically applying dark-mode adjustments to derived elements like borders through the mkBorder function and defaulting text to light colors (#eee) unless you specify otherwise.

Is there a performance impact when enabling darkMode?

The performance impact is negligible. Enabling darkMode triggers additional color calculations during theme initialization—such as darkening scale palettes by 75% rather than 25%—which occur once per diagram render. These calculations involve simple color manipulation functions in the theme base class and do not significantly affect rendering performance in the mermaid-js/mermaid library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}