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.
| Theme | What it looks like | Good for | Minimum version |
|---|---|---|---|
default | Lavender nodes, purple borders | General docs | Any |
neutral | Greys and black lines | Printed, black-and-white pages | Any |
dark | Dark nodes, light text | Dark pages | Any |
forest | Shades of green | A softer palette | Any |
base | Plain starting point | Custom colors with themeVariables | 8.7.0 |
redux, redux-dark | Monochrome, newer geometry and type | Color you assign yourself | 11.14.0 |
redux-color, redux-dark-color | A different color per entity, actor or series | Busy diagrams | 11.14.0 |
neo, neo-dark | Flatter and softer, made for look: neo | A lighter, modern style | 11.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:
- The diagram's own frontmatter or
%%{init}%%directive. - The options passed to
mermaid.initialize(). - The diagram type's default (the Mermaid 12 per-diagram defaults).
- The global default:
defaulttheme,classiclook.
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 onforestordarkaren'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, soprimaryColor: #dbeafeunquoted gives an empty value. - Expect derived colors. Mermaid calculates some colors from others. Change
primaryColorand it adjustsprimaryBorderColor,secondaryColorandtertiaryColorunless you set them too.
These core variables do most of the work. Defaults come from the theming docs:
| Variable | Default | Controls |
|---|---|---|
primaryColor | #fff4dd | Node background; many colors derive from it |
primaryTextColor | #333, or a light grey with darkMode | Text inside primary nodes |
lineColor | Calculated from background | Arrows and edges |
background | #f4f4f4 | Used to pick contrasting colors |
noteBkgColor | #fff5ad | Note boxes |
fontFamily | trebuchet ms, verdana, arial | All diagram text |
fontSize | 16px | Base text size |
darkMode | false | How 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.
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:
pie1topie12for 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.