Skip to content
MermaidViewer

Mermaid themes

Mermaid themes, themeVariables, classDef and frontmatter. How to recolor a diagram without breaking dark mode.

By MermaidViewer editorsPublished Updated

Mermaid's defaults look good, but you'll often want diagrams that match your brand or document. There are three levels of control: pick a theme, tweak theme variables, and style individual elements.

1. Built-in themes

Mermaid ships five themes: default, neutral (great for print), dark, forest and base (the one designed for customisation). Switch themes in the MermaidViewer toolbar, or set it in the diagram itself with frontmatter:

mermaid
---
config:
  theme: forest
---
flowchart LR
    A --> B

2. Theme variables

With the base theme you can override colors and fonts using themeVariables. All other colors are derived automatically.

mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#ccfbf1"
    primaryBorderColor: "#0d9488"
    primaryTextColor: "#134e4a"
    lineColor: "#0f766e"
    fontFamily: "Inter, sans-serif"
---
flowchart LR
    A[Brand] --> B[Colors]

The older %%{init: {...}}%% directive on the first line still works too, if a platform doesn't support frontmatter.

3. Styling individual nodes

In flowcharts, classDef defines a style and ::: or class applies it. style targets a single node and linkStyle targets arrows by index.

mermaid
flowchart LR
    A[Normal] --> B[Important]:::hot --> C[Done]
    classDef hot fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style C fill:#dcfce7,stroke:#16a34a
    linkStyle 0 stroke:#94a3b8,stroke-dasharray:4

Tips for readable diagrams

  • Use color to encode meaning (status, ownership), not decoration.
  • Ensure enough contrast between text and fill — test in dark mode too.
  • Prefer the neutral theme for documents that will be printed in black and white.
  • Keep a snippet of your brand frontmatter so every diagram starts consistent.

Variables that actually move the picture

The theme list is a starting point. Once you care about mermaid themes matching a document, three variables do most of the work, and only if you set them on the base theme so Mermaid derives the rest of the palette from your values.

primaryColor is the fill on the main nodes. A flowchart box, a sequence actor, and plenty of other shapes pick it up. Choose a light fill if the page is light. #ccfbf1 is a pale teal. A saturated brand red as a fill makes the text sit on a loud background and fails as soon as the diagram has more than a few nodes.

lineColor is the arrow and the border family that follows the line. Set it to a darker shade of the same hue, such as #0f766e, so the edges stay visible on white and on a projector. If you leave lineColor alone and only change the fill, the arrows stay in the default gray and the diagram looks half finished.

fontFamily is the stack for labels. "Inter, sans-serif" or "Georgia, serif" is enough. Diagrams are not the place for a display face with a tiny x-height. Long labels wrap badly, and a host that doesn't have the font falls through the stack. Always end with sans-serif or serif.

Leave fontSize alone until a label collides with a shape. Bumping the size to fix one node makes every other label overflow. Shorten the label instead.

Set the text and the border next to the fill or the contrast work is incomplete. primaryTextColor should be a dark color when primaryColor is light, for example #134e4a. primaryBorderColor can match lineColor. Those five are the set worth keeping in a snippet. Secondary and tertiary colors matter for sequence and class diagrams, which use more than one fill. Change them when an actor and a note look unrelated. Ignore the long tail of variables until a specific shape is wrong.

Frontmatter or the init directive

Two syntaxes set those variables. They have to appear before the diagram keyword. Both produce a theme. They fail in different hosts.

Frontmatter is YAML between --- lines. Quote every hex color. In YAML, # starts a comment, so primaryColor: #ccfbf1 sets the color to empty and the rest of the line disappears. Quotes make it a string.

Mermaid diagram
mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#ccfbf1"
    primaryTextColor: "#134e4a"
    primaryBorderColor: "#0d9488"
    lineColor: "#0f766e"
    fontFamily: "arial, sans-serif"
---
flowchart LR
    A[Request] --> B{Paid?}
    B -->|Yes| C[Ledger]
    B -->|No| D[Retry]
Open in the live editor

The init directive is one line at the top of the block. It takes JSON. It is the older form, and it still works on hosts that ignore YAML frontmatter. GitHub and other pinned renderers have lagged on frontmatter before. If the theme silently does nothing, switch to init before you blame the color.

Mermaid diagram
mermaid
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#ccfbf1", "primaryTextColor": "#134e4a", "primaryBorderColor": "#0d9488", "lineColor": "#0f766e", "fontFamily": "arial, sans-serif"}}}%%
flowchart LR
    A[Request] --> B{Paid?}
    B -->|Yes| C[Ledger]
    B -->|No| D[Retry]
Open in the live editor

Keep the directive on the first line. A comment above it, or a blank line some hosts trim badly, and the directive is skipped or reported as a parse error. Frontmatter has the same rule: it is the start of the mermaid block, not the start of the Markdown file. A --- block at the top of a Markdown document is the page's own frontmatter. The site generator will eat it. Put the theme inside the fence.

Pick one form per diagram. Two configs in one block fight, and the winner depends on the version. Store the JSON or the YAML in a snippet your team pastes, so the brand doesn't drift one diagram at a time.

theme: base is the theme that exists so you can override variables. Setting primaryColor on top of a named palette often looks like the override was ignored, because that palette writes its own colors after yours. Switch to base, then set the variables.

classDef pitfalls

classDef paints flowchart nodes with hard-coded CSS. It does not inherit the theme. That is useful for a status color and dangerous for everything else.

Define the class, then attach it with ::: on the node or with a class line. Include color, the text color, whenever you include fill. A fill without a text color keeps whatever text color the theme chose. On a light fill that is fine in the default theme and unreadable when the theme flips the text to white.

Mermaid diagram
mermaid
flowchart LR
    A[Request] --> B[Paid]:::ok --> C[Failed]:::bad
    classDef ok fill:#dcfce7,stroke:#166534,color:#14532d
    classDef bad fill:#fee2e2,stroke:#991b1b,color:#7f1d1d
Open in the live editor

The pitfalls that waste an afternoon:

The class name is not a CSS class in your stylesheet. Naming it btn does nothing to the page, and a page rule named ok does nothing to the node. The name only exists inside the diagram.

A typo is silent. class B okk leaves B on the theme colors. There is no error. Compare the rendered fill to the one you expected.

Redeclaring a node drops the class. The first line B[Paid]:::ok and a later B[Paid in full] can keep the id and replace the label. Put :::ok on the declaration you want to keep. The last label wins, and the class is whatever that declaration included.

classDef default restyles every node that doesn't have its own class. A later node you added in a hurry inherits the brand fill. Use named classes for the few nodes that carry meaning, and leave the rest on the theme.

style B fill:#dcfce7 overrides the class for the properties it sets. A later style line is the one on the screen. If the text color "randomly" changes, look for a style under the classDef.

Commas separate properties. fill:#dcfce7 stroke:#166534 without a comma is invalid. Hex values in classDef don't use YAML rules, so #dcfce7 is fine here and fatal in frontmatter. Different syntax, same file, easy to mix up.

classDef doesn't apply to sequence participants or ER entities. Those diagrams take color from theme variables. If a class line is ignored, you are probably not in a flowchart.

Contrast on a dark page

GitHub, Obsidian, and the editor can all show the same source on a dark page. The theme may switch to dark. Your classDef fills do not. A mint rectangle with white text from the dark theme fails contrast. The fix is the color property in the class, set to a dark ink, as in the example above. Then the chip stays light and the words stay dark, in both modes.

Check a dark preview before you merge. In the editor, toggle the page. On GitHub, look at the file with the dark theme enabled. You are looking for gray-on-mint and white-on-pale, not for a perfect brand match.

Theme variables are the better path when the whole diagram should follow the page. A dark primaryColor with a light primaryTextColor belongs in a dark-theme config. A light pair belongs in the light config. Shipping one hard-coded light palette and hoping the host adapts it will fail, because classDef and explicit variables win over the host's guess.

Don't encode status only with color. The labels in the example say Paid and Failed. A reader who can't distinguish the green from the red still gets the word. Contrast helps. The word is the actual content.

Large areas of pure #000 or pure #fff next to thin gray lines flicker on projectors. Move the text color a step off pure black (#134e4a in the teal example) and the line color a step off pure gray. You get edges you can see in a meeting room.

Before and after

The same four nodes, first with no config. This is the "before". Labels and edges are the whole design. It is readable, and it doesn't match anyone's brand. That is acceptable for a pull request description. It is thin for a public doc that already has a typeface and a color.

Mermaid diagram
mermaid
flowchart LR
    A[Request] --> B{Paid?}
    B -->|Yes| C[Ledger]
    B -->|No| D[Retry]
Open in the live editor

The "after" keeps every id and every label. It only adds base and the five variables. Arrows pick up lineColor. Boxes pick up primaryColor and primaryTextColor. The font stack applies if the host has Arial, and falls back to the generic sans if it doesn't.

Mermaid diagram
mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#ccfbf1"
    primaryTextColor: "#134e4a"
    primaryBorderColor: "#0d9488"
    lineColor: "#0f766e"
    fontFamily: "arial, sans-serif"
---
flowchart LR
    A[Request] --> B{Paid?}
    B -->|Yes| C[Ledger]
    B -->|No| D[Retry]
Open in the live editor

If the after looks identical to the before, the host ignored frontmatter. Paste the init directive version from above. If the after looks right in the editor and wrong on GitHub, trust GitHub for anything that ships there, and keep the init form in the file.

Add classDef only after this lands. Status colors on Paid and a future Failed node are a second step. Doing both at once makes it hard to see which syntax the host dropped. One change, render, then the next. The export guide is where you bake the finished theme into a PNG for a tool that will never read the variables. Free PNG is 1× with a watermark, Starter goes to 4×, and Pro goes to 8×. SVG download is on Pro.

A theme that survives a dark README

Pick the theme for the place the fence will be read, not for the screenshot you liked in the editor. GitHub's README is light for many people and dark for others, and a primaryColor of near-black text on a near-black fill disappears for half of them. If you cannot test both, stay on default or neutral and use classDef only for one status that still has a visible border.

When you do set themeVariables, change one variable, render, then change the next. lineColor and primaryBorderColor are the pair that most often collide: the arrow vanishes into the node outline. Leave fontFamily alone unless the host is a page you control. A custom font in frontmatter is a request, and GitHub will ignore it, which is fine as long as you did not depend on the width of that font to fit a label.

Keep hex values in the frontmatter, not scattered through style lines, once more than two nodes share a color. A later rebrand is then one edit. The cheat sheet lists the directives. The editor applies them as you type, which is the check before you push.