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

> Discover how Mermaid's darkMode option recalculates colors for dark backgrounds without overriding your chosen theme. Enhance readability and learn about theme interaction.

- Repository: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)
- Tags: deep-dive
- Published: 2026-02-23

---

**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`](https://github.com/mermaid-js/mermaid/blob/main/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.

```javascript
// 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`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/themes/theme-helpers.js) uses the `darkMode` flag to calculate appropriate border luminance:

```javascript
// 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:

```mermaid
---
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`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/docs/config/theming.md):

```javascript
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:

```javascript
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`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/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.