How to add color to Mermaid diagrams

Is a colored Mermaid diagram still Markdown?

A colored Mermaid diagram sits inside a valid Markdown file, but the diagram code and its colors are a separate format called Mermaid. Knowing the difference saves a lot of confusion.

The file is Markdown. A Mermaid diagram sits inside an ordinary Markdown code block, the kind that starts with three backticks and a label:

    ```mermaid
    graph TD
      A --> B
    ```

The diagram code inside the block is Mermaid. Markdown's only job is to say this block is labeled mermaid. Whether it turns into boxes and arrows is up to the app you open it in.

Colors work the same way. style, classDef and %%{init}%% are Mermaid commands, not Markdown. So:

• In an app that draws Mermaid, you see a colored diagram.
• In an app that doesn't, you see the code, colors and all, as text.
• In every app, the file still opens. It's valid Markdown either way.

If you're new to reading the diagram code itself, start with how to read Mermaid diagrams. For the Markdown around it, see what a .md file is.

markdown is the envelope. mermaid is the letter inside.

Method 1: Color one Mermaid box with style

The quickest way to color one box in a Mermaid diagram is a style line. Add it anywhere inside the diagram, usually at the bottom.

graph LR
  A[Draft] --> B[Review] --> C[Ship]
  style C fill:#DDEFDD,stroke:#1E5A1E,color:#1E5A1E

The pattern is style, the box's ID, then settings separated by commas. This table lists the settings you can use.

The ID is the short name before the bracket. In C[Ship], the ID is C and the label is Ship. Always style the ID, not the label.

Method 2: Reuse Mermaid colors with classDef

classDef lets you define a color once in a Mermaid diagram and attach it by name to every box that shares a meaning, like done, in progress and blocked.

graph TD
  A[Research]:::done --> B[Design]:::done
  B --> C[Build]:::active
  C --> D[Test]:::todo
  C --> E[Legal review]:::blocked
  classDef done fill:#DDEFDD,stroke:#1E5A1E,color:#1E5A1E
  classDef active fill:#FBF3C4,stroke:#6B5C14,color:#141414
  classDef todo fill:#FFFFFF,stroke:#B8BFCC,color:#555555
  classDef blocked fill:#FDE7EC,stroke:#8C2136,color:#8C2136

There are two parts:

1. Define a class: classDef done fill:#DDEFDD,stroke:#1E5A1E
2. Attach it with three colons after the box: A[Research]:::done

You can also attach one class to several boxes at once with class A,B done. This is the method to ask your AI for, because the colors then carry meaning, and changing one classDef line recolors every matching box.

How do I color the arrows in a Mermaid flowchart?

Mermaid colors arrows with linkStyle and their number, counting from 0 in the order they appear.

graph LR
  A[Order] --> B[Pay] --> C[Ship]
  linkStyle 1 stroke:#FF5A36,stroke-width:3px

Here linkStyle 1 is the second arrow, from Pay to Ship. Use linkStyle default to change every arrow at once.

Method 3: Theme the whole Mermaid diagram with init

To change every color in a Mermaid diagram at once, put an init line as the very first line inside the block. This works for all diagram types, including pie charts and Gantt charts, where style and classDef don't apply.

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#DCE9FB','primaryBorderColor':'#1B4C82','lineColor':'#6B7592'}}}%%
graph LR
  A[Ask] --> B[Draft] --> C[Read]

Setting theme to base means start from a blank theme, so your colors aren't mixed with a built-in palette. This table lists the theme variables you'll use most.

Mermaid also ships ready-made themes: default, neutral, dark and forest. Swap 'base' for one of those and drop the variables to use it.

Which Mermaid diagram types accept which colors?

Each Mermaid diagram type accepts different color commands. This table shows which commands work in which diagram.

A colored pie chart

A Mermaid pie chart takes its slice colors from pie1, pie2 and so on in an init line.

%%{init: {'theme':'base','themeVariables':{'pie1':'#FF5A36','pie2':'#4A9FE8','pie3':'#E9CF5E'}}}%%
pie title Where the week went
  "Hunting for files" : 42
  "Actually reading" : 31
  "Fixing formatting" : 27

A Gantt chart with status colors

A Mermaid Gantt chart colors its bars from status tags, with no extra code needed:

gantt
  dateFormat YYYY-MM-DD
  section Build
  Reader :done, 2026-09-01, 10d
  Search :active, 2026-09-08, 10d
  section Ship
  Beta :crit, 2026-09-18, 7d

done bars are muted, active bars are highlighted, and crit bars are marked as critical.

How do I choose Mermaid colors that stay readable?

Mermaid colors stay readable when you follow six simple rules, so the color makes a diagram quicker to read:

• Use pale fills and dark text. Light backgrounds with dark borders and text read well on screen and in print. Save strong fills for one or two boxes you want to stand out.
• Give each color one meaning. Green for done, yellow for in progress, red for blocked. Don't reuse a color for something unrelated.
• Don't rely on color alone. About 1 in 12 men has some form of color vision deficiency (National Eye Institute). Keep words in the labels too: Blocked: legal review, not just a red box.
• Stick to three or four colors. More than that and nothing stands out.
• Check the contrast. Text should be clearly darker than its fill. If you have to squint, darken the text color.
• Think about dark pages. Colors you set yourself are drawn as written, even when the reader shows a dark page. Always set a dark text color along with a pale fill. If you set only the fill, the text may switch to a light color for the dark page and vanish into your pale box.

This table gives a four-color set that works well together.

How do I get Claude or ChatGPT to color Mermaid diagrams?

Claude, ChatGPT and Cursor will add Mermaid colors if you ask, so you don't need to write any of this by hand. These prompts work well:

Draw this as a Mermaid flowchart. Color each step with classDef: done in green, in progress in yellow, blocked in red. Use pale fills with dark text.

Recolor this Mermaid diagram using these colors: fill #DCE9FB, border #1B4C82, arrows #6B7592. Use an init line with theme base.

Turn this list of tasks into a Mermaid Gantt chart. Mark finished tasks as done, the current one as active, and anything overdue as crit.

If you want every diagram to match, add a line to your project instructions or CLAUDE.md: When drawing Mermaid diagrams, use classDef colors: done #DDEFDD, active #FBF3C4, blocked #FDE7EC.

ask once, in your instructions. every diagram after that comes out matching.

Why don't my Mermaid diagram colors show?

Mermaid colors usually fail to show because the app doesn't draw Mermaid, the app strips diagram styles, or the code has a small mistake. This table matches what you see to the likely cause and the fix.

Where Mermaid diagrams draw with colors varies. GitHub, GitLab, Obsidian, Typora and Notion all draw Mermaid, though apps differ in which styling they keep.

One Clear Reader draws diagrams on your Mac with Mermaid 11 in its strict security mode. Strict mode switches off clickable links and HTML inside diagrams (Mermaid docs). It leaves Mermaid's own color settings alone, so style, classDef, linkStyle and init colors all come through.

When a Mermaid diagram sets no colors in One Clear Reader, it uses its own palette, matched to a light or dark page. If a diagram won't draw at all, One Clear Reader tells you which line has the syntax error. To use a colored diagram somewhere else, Copy SVG (Pro) copies the drawing for design tools, and Save as PDF (Pro) keeps it in the page.

Questions people ask