What's the basic syntax for a Mermaid pie chart?

Start with pie, optionally add a title, then list each slice on its own line as "Label" : value. Example: pie title Traffic by source\n "Organic" : 55\n "Referral" : 25\n "Direct" : 20. Labels are always wrapped in double quotes — Mermaid requires this even for single-word labels. Values are plain numbers; Mermaid calculates percentages for the display automatically based on the sum of values.

Do the values need to sum to 100?

No. Mermaid scales the slices to whatever total you give it. "A" : 60 plus "B" : 40 produces a 60/40 split, but "A" : 300 plus "B" : 200 produces the same visual split (the same 60/40 ratio). Use the absolute values that match your data — Mermaid handles the percentage math. This is also why you can use any unit (visitors, dollars, hours) — the diagram only cares about the proportions.

How do I show absolute values instead of percentages?

Add showData after the pie keyword: pie showData title Traffic by source. By default Mermaid displays each slice's percentage; showData switches to (or adds, depending on Mermaid version) the absolute values you supplied. Useful when the counts matter as much as the proportions — "500 users" tells a different story from "58%" even when both describe the same slice.

When should I use a bar or sankey chart instead?

Pie charts work for six or fewer slices showing a single share-of-total view. Beyond six slices, the visual angles become too similar to distinguish — switch to a horizontal bar chart for category comparison (Mermaid's xychart-beta covers this) or a sankey diagram if there are multiple stages (source → destination → final). Pie is also a poor choice when trends over time matter — use a multi-line chart for that.

Why does my pie chart fail to render?

Almost always missing quotes on slice labels. Mermaid requires every label to be wrapped in double quotes, even labels without spaces or special characters: "Organic" : 55 parses, Organic : 55 doesn't. Second most common cause: extra whitespace inside the value field — "Organic" : 55 with trailing whitespace can confuse some Mermaid versions. Use a code editor that highlights trailing whitespace to catch this.

Diagram type

Mermaid Pie Chart Syntax & Examples

Reference for Mermaid pie chart syntax — pie keyword, title declaration, showData option, and slice format ("Label" : value). Copy-paste examples for traffic / cost breakdowns.

Syntax reference, layout guidance, and ready-to-open examples for this diagram type.

At a glance

A syntax reference for Mermaid's pie chart grammar — read this when you need the exact way to declare a title, toggle data display, or format slice values, then try the result in the editor.

What is a Mermaid pie chartBasic syntax — pie + slicesTitle — pie titleshowData — display absolute values alongside labelsCommon patterns & gotchas

Syntax reference

Mermaid pie chart constructs, one per row

Construct	Syntax	Notes
Diagram keyword	`pie`	First line. The title may ride on the same line: `pie title Traffic by source`.
Chart title	`title Traffic by source`	Either on its own line under `pie`, or appended to the `pie` line itself.
Show raw values	`pie showData`	Prints each slice's number next to its label as well as the percentage.
Slice	`"Organic" : 55`	Quoted label, colon, number. One slice per line.
Fractional values	`"Paid" : 12.5`	Decimals are accepted; percentages are computed from the totals, so the numbers need not sum to 100.
Slice order	`source order`	Slices are laid out in the order written — there is no sort directive.

Syntax reviewed 8 August 2026

Rendered proof

Pie chart with three named slices.

Theme · Slate

Open this diagram in editor

View Mermaid sourcePlain-text diagram syntax — copy or edit directly.

diagram.mmd

1pie title Traffic by source
2  "Organic" : 55
3  "Referral" : 25
4  "Direct" : 20

Open in editor with this template

What is a Mermaid pie chart

A pie chart shows how a quantity divides into a small number of named slices, each representing a share of the total. It is the right shape when the question is what-share-does-each-category-have-of-the-whole: traffic source breakdown, cost allocation, time spent by category, simple proportional views. Mermaid pie charts are deliberately minimal — no nested rings, no exploded slices, no animations. If your data has more than 6-7 categories, the chart becomes unreadable and a bar chart or sankey diagram communicates the same information more clearly.

Basic syntax — pie + slices

Every Mermaid pie chart starts with the pie keyword. Each slice is declared on its own line in the format "Label" : value. The label is always wrapped in double quotes (even if it has no spaces); the value is a plain number. Mermaid automatically calculates the percentage each slice represents of the total — you supply the absolute values and Mermaid does the math. Slice order matches source order: the first declared slice gets the first colour from Mermaid's palette and renders starting at the top.

pie — diagram type keyword
"Label" : value — one line per slice (label always quoted)
Slice order = source order; first slice starts at the top

Title — `pie title`

Add a title with the title keyword on the same line as pie, or as a separate title declaration before the slices. The forms pie title Traffic by source and pie\n title Traffic by source both work — pick whichever reads better in your source. The title appears centred above the chart in the rendered output. Pie charts without titles are valid but lose context — when the chart is pulled out of its surrounding documentation (pasted into a slide deck, exported for a status report), the title is what tells the reader what they're looking at.

showData — display absolute values alongside labels

By default a Mermaid pie chart shows percentages on slices. Add showData after the pie keyword to show the absolute values instead (or in addition, depending on Mermaid version): pie showData title Traffic by source. This is useful when the values themselves matter — "500 / 250 / 100 users" tells a different story from "58% / 29% / 12%" even when the proportions are identical. For internal dashboards or status reports where stakeholders need to know the absolute counts, showData is the right default.

Common patterns & gotchas

Two patterns cover almost every real pie chart. Source breakdown (Organic / Referral / Direct / Paid traffic, or by-channel revenue split) is the most common. Cost / time allocation (engineering / sales / marketing / ops as % of budget or headcount) is the second. The most common gotcha: forgetting to quote the label — Organic : 55 doesn't parse, "Organic" : 55 does. Labels are always quoted, even when there are no spaces or special characters. Second gotcha: using percentages as input values when the percentages don't add to 100 — Mermaid scales the slices to whatever total you give it, so "A" : 60, "B" : 50 produces slices of 60/110 and 50/110, not the 60%/40% you might have intended.

Slice labels are always double-quoted — "Organic" : 55, not Organic : 55
Values are scaled to the total — Mermaid doesn't require them to sum to 100
Six or fewer slices reads cleanly; beyond that pick a bar or sankey chart