Theme Switching

When autoTheme is on (the default), the integration reads data-theme from both <html> and <body>.

data-theme="dark" maps to Mermaid’s dark theme.
data-theme="light" maps to Mermaid’s default theme.
If neither attribute is set, it falls back to the prefers-color-scheme media query.

This site uses Starlight’s dark/light toggle, which sets data-theme on <html>. Try the toggle in the header — the diagrams re-render with the new theme.

MutationObserver and debounce

A MutationObserver watches for data-theme changes. When the attribute flips, the diagrams re-render after a 50ms debounce.

That debounce matters: during View Transitions, the DOM swap can remove and re-add the attribute in the same tick, and without it you’d get a double render. The debounce coalesces those rapid flips into a single re-render.

Only already-rendered diagrams re-render

Theme switches re-render diagrams that have already been processed. Diagrams that were deferred by lazy loading stay deferred until they enter the viewport — switching themes does not force them to render.

Disabling auto theme

To use a single fixed theme, set autoTheme: false and pick a theme. The MutationObserver is not installed in that mode, so theme switches do not trigger re-renders.

mermaid({
  theme: 'forest',
  autoTheme: false,
});