Mermaid JS Themes: Built-in List, themeVariables, Dark Mode

November 11, 2026 · 11 min read

Mermaid JS Themes: Built-in Options, themeVariables and Dark Mode

Mermaid JS themes control the colors, fonts and borders of every diagram Mermaid draws. You pick one with a theme key in the diagram's frontmatter or in mermaid.initialize(). The five classic themes work in any current renderer, while the newer redux and neo themes need Mermaid 11.14.0 or later.

Which Mermaid JS Themes Are Built In?

Mermaid has shipped configurable themes since version 8.7.0, according to the official theming docs. The list grew with 11.14.0 in April 2026, so the version your renderer runs decides which names work.

ThemeWhat it looks likeGood forMinimum version
defaultLavender nodes, purple bordersGeneral docsAny
neutralGreys and black linesPrinted, black-and-white pagesAny
darkDark nodes, light textDark pagesAny
forestShades of greenA softer paletteAny
basePlain starting pointCustom colors with themeVariables8.7.0
redux, redux-darkMonochrome, newer geometry and typeColor you assign yourself11.14.0
redux-color, redux-dark-colorA different color per entity, actor or seriesBusy diagrams11.14.0
neo, neo-darkFlatter and softer, made for look: neoA lighter, modern style11.14.0

The redux and neo theme files don't exist in the Mermaid 11.13.0 source and first appear in the 11.14.0 release. An older renderer doesn't show an error when it meets an unknown name. It skips the theme and the diagram keeps whatever theme the page already uses.

Mermaid 12 also changed some defaults. Flowcharts, sequence, class, state, ER and requirement diagrams, plus a few beta types, now start with redux-color and the neo look. Put theme: default and look: classic in a diagram's config to get the older appearance back.

A look is a separate setting from a theme. It changes the drawing style (classic, handDrawn, and neo from 11.14.0) while the theme supplies the colors.

How Do You Change the Theme of a Mermaid Diagram?

You can set a theme for one diagram or for every diagram on a site. The one-diagram setting wins when both exist.

Per diagram: frontmatter config

Put a YAML block at the very top of the Mermaid code, before the diagram type. Frontmatter config arrived in Mermaid 10.5.0.

```mermaid
---
config:
  theme: forest
---
flowchart LR
    A[Idea] --> B[Draft] --> C[Publish]
```

This renders a left-to-right flowchart with pale green boxes and dark green borders. Nothing else on the page changes, because the config only applies to this one diagram.

Per diagram: the older init directive

Many tutorials still teach a one-line directive: %%{init: {'theme': 'forest'}}%% placed as the first line of the diagram. The directives page marks it deprecated from v10.5.0 in favor of frontmatter. Many renderers still parse it, and it's your only option on a renderer older than 10.5.0.

```mermaid
%%{init: {'theme': 'forest'}}%%
flowchart LR
    A[Idea] --> B[Draft] --> C[Publish]
```

This produces the same green diagram as the frontmatter version. For new diagrams, use frontmatter: it's easier to read and it's the documented method.

For a whole site: mermaid.initialize()

If you embed Mermaid in your own site or docs tool, set the theme once when you start it:

mermaid.initialize({ startOnLoad: true, theme: 'neutral' });

Every diagram on that page now uses neutral unless it sets its own theme. The docs give this order, highest priority first:

  1. The diagram's own frontmatter or %%{init}%% directive.
  2. The options passed to mermaid.initialize().
  3. The diagram type's default (the Mermaid 12 per-diagram defaults).
  4. The global default: default theme, classic look.

Some hosts mark config keys as secure, which stops diagrams from overriding them. If a per-diagram theme does nothing, the host may have locked it.

Customizing Colors with themeVariables and the Base Theme

To build your own Mermaid JS theme, start from base and override themeVariables. Here's a blue flowchart:

```mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: '#dbeafe'
    primaryTextColor: '#1e3a8a'
    primaryBorderColor: '#1d4ed8'
    lineColor: '#1d4ed8'
    fontFamily: 'Georgia, serif'
---
flowchart LR
    A[Draft] --> B{Review}
    B -->|approved| C[Merge]
    B -->|changes| A
```

The nodes fill light blue with dark blue text and borders, the arrows turn blue, and labels switch to Georgia. Four rules decide whether your variables take effect:

  • Use base. The docs say it's the only theme you can modify. Overrides on forest or dark aren't supported and may only partly apply.
  • Use hex values. The theming engine only recognizes hex colors, not names such as red. A name sometimes fills a node anyway, but the docs don't support it.
  • Quote hex values in YAML. A # after a space starts a YAML comment, so primaryColor: #dbeafe unquoted gives an empty value.
  • Expect derived colors. Mermaid calculates some colors from others. Change primaryColor and it adjusts primaryBorderColor, secondaryColor and tertiaryColor unless you set them too.

These core variables do most of the work. Defaults come from the theming docs:

VariableDefaultControls
primaryColor#fff4ddNode background; many colors derive from it
primaryTextColor#333, or a light grey with darkModeText inside primary nodes
lineColorCalculated from backgroundArrows and edges
background#f4f4f4Used to pick contrasting colors
noteBkgColor#fff5adNote boxes
fontFamilytrebuchet ms, verdana, arialAll diagram text
fontSize16pxBase text size
darkModefalseHow derived colors are calculated

Try it below in light mode. Change primaryColor to another hex value and the nodes recolor as you type. The demo uses a tilde fence and a one-line YAML config, which render the same way.

Themed flowchart

---
config: {theme: base, themeVariables: {primaryColor: '#dbeafe', primaryTextColor: '#1e3a8a', primaryBorderColor: '#1d4ed8', lineColor: '#1d4ed8', fontFamily: 'Georgia, serif'}}
---
flowchart LR
A[Draft] --> B{Review}
B -->|approved| C[Merge]
B -->|changes| A

Change primaryColor to another hex value and the nodes recolor.
Use light mode to see your colors: dark mode applies the site's own diagram palette.

58 words447 characters14 lines
Markdown

Theme Variables for Flowcharts, Sequence Diagrams and Pie Charts

Beyond the core set, each diagram type reads its own variables. If you need a refresher on the diagram syntax itself, see our guide to Mermaid diagrams in Markdown. The names below are the ones you'll reach for most:

  • Flowchart: nodeBorder, clusterBkg (subgraph fill), clusterBorder, edgeLabelBackground, nodeTextColor.
  • Sequence diagram: actorBkg, actorBorder, actorTextColor, signalColor, activationBkgColor.
  • Pie chart: pie1 to pie12 for the slices, pieStrokeColor (default black), pieOpacity (default 0.7), pieTitleTextSize (default 25px).

Pie charts are where custom colors pay off fastest, because the defaults derive every slice from primaryColor:

```mermaid
---
config:
  theme: base
  themeVariables:
    pie1: '#2563eb'
    pie2: '#16a34a'
    pie3: '#f59e0b'
    pieOpacity: '1'
---
pie title Time spent
    "Writing" : 55
    "Review" : 30
    "Meetings" : 15
```

The three slices render solid blue, green and amber. Setting pieOpacity to 1 removes the washed-out look the 0.7 default gives.

How Do You Make Mermaid Diagrams Follow Dark Mode?

Two settings sound alike but do different jobs. The dark theme recolors the diagram itself for dark pages. The darkMode: true theme variable only changes how Mermaid calculates derived colors, which matters when you build a dark palette on base.

On your own site, the catch is that Mermaid replaces each code block with an SVG once. Toggling the page theme doesn't touch diagrams already drawn, so you re-render them:

const media = window.matchMedia('(prefers-color-scheme: dark)');
const blocks = document.querySelectorAll('.mermaid');
const sources = Array.from(blocks, (el) => el.textContent);

async function renderDiagrams() {
  blocks.forEach((el, i) => {
    el.removeAttribute('data-processed');
    el.textContent = sources[i];
  });
  mermaid.initialize({ startOnLoad: false, theme: media.matches ? 'dark' : 'default' });
  await mermaid.run({ nodes: blocks });
}

media.addEventListener('change', renderDiagrams);
renderDiagrams();

The code saves each block's source before the first run, because Mermaid swaps it for SVG. It also clears the data-processed attribute, since mermaid.run() skips any block that already has it. A diagram that sets its own theme in frontmatter keeps that theme in both modes.

Our Markdown editor handles this for you: its preview redraws diagrams with Mermaid's dark or default theme whenever you switch the site between light and dark. The Mermaid editor tool adds a theme menu with Default (follows the site theme), Dark, Forest and Neutral, and exports the diagram as SVG or PNG. For command-line export with a theme flag, see our Mermaid to PNG guide.

Do Mermaid JS Themes Work on GitHub and in Other Apps?

The theme syntax is the same everywhere, but each app ships its own Mermaid version and its own defaults.

GitHub renders Mermaid fences in Markdown files, issues, pull requests, discussions and wikis, per GitHub's diagram docs. GitHub controls the Mermaid version, so check it with a diagram containing only the word info. If it reports a version below 11.14.0, stick to the five classic themes. GitHub may also restyle diagrams for its light or dark mode, so preview the file before you commit it. Our GitHub Markdown cheat sheet covers the rest of GFM.

Desktop apps such as Typora and Obsidian bundle their own Mermaid release, so run the same version check there. Typora sets its diagram theme through CSS variables, which our Typora Mermaid guide lists.

Our editor runs a Mermaid 11 release older than 11.14. Frontmatter config and the %%{init}%% directive both apply in light mode, including base with themeVariables. The redux and neo names fall back to the editor's normal diagram theme. In dark mode, the editor's own dark palette replaces many of your colors.

Don't confuse these with Markdown CSS themes. A Markdown CSS theme styles the rendered page, while a Mermaid theme styles only the diagram's SVG.

Themes vs classDef and style: Picking the Right Tool

A theme recolors every node in a diagram at once. When you only need to flag one or two nodes, use classDef and class in a flowchart instead:

```mermaid
flowchart LR
    A[Build] --> B[Test] --> C[Ship]
    classDef warn fill:#fee2e2,stroke:#b91c1c
    class B warn
```

Only the Test node turns pale red with a red border, and the rest keep the active theme. The one-off form style B fill:#fee2e2 does the same for a single node without naming a class. ER diagrams accept the same statements from Mermaid 11.5.0, as our Mermaid ER diagram guide shows.

We prefer base plus three or four variables over a hand-built theme object. You get a consistent palette, and Mermaid's derived colors fill the gaps you'd otherwise forget. The limitation is that a theme can't vary per node, so for status colors you'll still combine it with classDef.

Quick Answers About Mermaid JS Themes

Mermaid JS themes come down to three choices. Pick a classic theme your renderer's version supports, recolor base with hex themeVariables when you need your own palette, and re-render on theme changes if you host the diagrams yourself. Paste any diagram from this guide into the editor to see it render live, or open the Mermaid editor tool to compare themes and export the result.