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.
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.
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
1pie title Traffic by source2 "Organic" : 553 "Referral" : 254 "Direct" : 20What 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