Themes and Styling

The built-in renderer resolves a Mermaid theme for each render, then exposes CSS variables for its surrounding controls. Theme names affect Mermaid SVG output; --ncm-* variables affect the module's wrapper, toolbar, overlays, and zoom UI.

Set light and dark defaults

Configure the themes selected by automatic color mode and reserved manual strategies:

export default defineNuxtConfig({
  contentMermaid: {
    theme: {
      light: 'default',
      dark: 'dark',
    },
  },
})

The defaults are light: 'default' and dark: 'dark'. The deprecated theme.useColorModeTheme key has no effect.

Control a theme manually

useMermaidTheme() is a Nuxt auto-import after the module is enabled. It returns app-scoped reactive state and methods:

<script setup lang="ts">
const {
  currentTheme,
  setMermaidTheme,
  getMermaidTheme,
  resetMermaidTheme,
} = useMermaidTheme()

function toggleDiagramTheme() {
  setMermaidTheme(currentTheme.value === 'dark' ? 'light' : 'dark')
}
</script>

<template>
  <button type="button" @click="toggleDiagramTheme">
    Toggle diagram theme
  </button>
</template>

• currentTheme is a reactive Ref containing the manual override. It represents the current manual mode, which is not necessarily the final theme name passed to Mermaid.
• setMermaidTheme(mode) sets it and getMermaidTheme() returns it.
• resetMermaidTheme() is equivalent to setMermaidTheme(null).

Pass null to return to automatic selection. Do not import this composable from the package root; Nuxt provides the auto-import.

Distinguish strategies from theme names

'light' and 'dark' are reserved strategies, not ordinary direct theme-name values:

setMermaidTheme('dark') // configured dark strategy
setMermaidTheme('forest') // direct Mermaid theme
setMermaidTheme(null) // automatic mode

Understand theme resolution

The package's Theme Resolution Policy is, highest to lowest:

1. config.theme from the selected diagram configuration source: Page Mermaid Config for a Markdown page, or Direct Mermaid Config for a Vue component.
2. The manual mode from useMermaidTheme().
3. The current @nuxtjs/color-mode value, when that module is installed.
4. contentMermaid.loader.init.theme (falling back to the light configured theme, then 'default').

The config.theme in step 1 comes from page config or component config. Mermaid YAML frontmatter and %%{init: ...}%% directives remain source-level configuration interpreted according to Mermaid's own rules, so they are outside this package-owned theme policy.

In automatic color-mode selection, dark uses theme.dark; every other detected color-mode value uses theme.light. Mermaid YAML frontmatter and directives remain Mermaid-owned source syntax, so consult Writing Diagrams for their boundary.

Use color mode and manual control together

When @nuxtjs/color-mode is present, diagrams follow it while manual mode is null. Set a manual mode only when a view needs to override it, then reset it to resume color-mode selection:

const { resetMermaidTheme, setMermaidTheme } = useMermaidTheme()

setMermaidTheme('dark')
resetMermaidTheme()

Manual state is app-scoped, so plan a reset when leaving a view that deliberately locks a diagram theme.

Override the built-in styling hooks

Set variables in application CSS. This supplies a compact branded light/dark palette:

:root {
  --ncm-code-bg: #f3f4f6;
  --ncm-code-bg-hover: #e5e7eb;
  --ncm-border-color: #d1d5db;
  --ncm-text: #111827;
  --ncm-text-muted: #4b5563;
  --ncm-text-xmuted: #6b7280;
  --ncm-overlay-bg: #f9fafb;
}

html[data-theme='dark'],
.dark {
  --ncm-code-bg: #111827;
  --ncm-code-bg-hover: #1f2937;
  --ncm-border-color: #374151;
  --ncm-text: #f9fafb;
  --ncm-text-muted: #d1d5db;
  --ncm-text-xmuted: #9ca3af;
  --ncm-overlay-bg: #111827;
}

Surface, border, and text hooks

Overlay, cursor, and hint hooks

Toolbar and zoom layout hooks

The renderer sets --ncm-icon-size, --ncm-toolbar-height, and cursor variables dynamically. Override them only when you also account for the matching control size and interaction state.