Basic pie chart example
pie showData
title Where our traffic comes from
"Organic search" : 48
"Direct" : 22
"Social" : 14
"Referral" : 10
"Email" : 6Mermaid pie charts are the fastest way to show proportions in documentation. You list labels and values, and Mermaid computes the percentages, colors and legend for you.
They're handy for survey results, budget splits, traffic sources and test coverage summaries — anywhere a quick visual beats a table.
When to use a pie chart
- Survey and poll results
- Budget and cost breakdowns
- Traffic or revenue by channel
- Language or test coverage summaries
Pie Chart syntax reference
| Syntax | What it does |
|---|---|
pie | Start a pie chart. |
pie showData | Also print raw values in the legend. |
title Text | Chart title. |
"Label" : 42 | One slice; values must be positive numbers. |
Pie Chart examples
Budget split
Values don't need to add up to 100 — Mermaid calculates percentages.
pie title 2026 Marketing Budget
"Content" : 35000
"Paid ads" : 25000
"Events" : 15000
"Tools" : 5000Shares of one total are the only story a pie can tell. A mermaid pie chart draws slices from the numbers you give, and the numbers are weights, not finished percentages, unless you made them add up that way. The syntax line is short. The mistakes are almost all about what the weights mean.
Weights, labels, and the title
Open with pie title and the title on the same line. Each slice is "Label" : 40. The quotes matter as soon as the label has a space or a capital that the lexer would rather treat as a new token. A bare Billing questions : 40 fails the parse.
Mermaid adds the values and gives each slice its fraction of that sum. 40 and 20 draw the same picture as 2 and 1. That's useful when you have raw counts. It's a trap when you type numbers you already think of as percents and they add up to 80. The chart will still fill the circle. The 40 will look like half, because 40 is half of 80. If you want the labels to match the angles, make the values sum to 100, or label the diagram as counts and let the angles be the percentages.
Four to six slices is the readable range. A slice under about five percent becomes a sliver with a legend line and no room for text. Fold the tail into "Other". If you need the tail explained, put a sentence under the diagram, not an eighth slice.
The title should say what the whole is. "Ticket mix" tells you the circle is all tickets. "Counts" doesn't. Readers assume a pie is exhaustive. If the chart omits a category, say so in the title or the caption.
Worked example
Support looked at one month of tickets. Billing is the largest share, access is next, bugs are smaller, and the rest is grouped.
pie title Ticket mix
"Billing" : 40
"Access" : 25
"Bugs" : 20
"Other" : 15These weights sum to 100, so the angles match the numbers a stakeholder will quote. Billing is two fifths of the circle. Access is a quarter. If the raw counts were 80, 50, 40, and 30, you could paste those instead and the picture would match, because the ratios match. Don't paste 80, 50, 40, and 30 and also tell people the slices are already percents.
"Other" is a decision. It hides the small categories so Bugs stays readable. If Other grows past Billing, stop grouping and split it. The pie is arguing that Billing dominates. When that stops being true, the grouping is the thing to change.
When this is the wrong diagram
An XY chart is the better picture when the question is how a number moves across months. A treemap is the better picture when the whole has nested parts, such as a budget inside departments. A pie chart has one level. Use it when every slice is a peer and the circle is the full set.
Common mistakes
- An unquoted multi-word label, such as
Billing questions : 40. The lexer stops on the extra word. Write"Billing questions" : 40. - Treating weights as percents when they don't sum to 100. The slice for 40 becomes 40 divided by the actual total, and the angle won't match the number you say out loud.
- One slice per rare category, until the legend is longer than the chart. Group the tail as
"Other". - A title that doesn't name the whole, so a reader can't tell whether the circle is one month of tickets or all tickets ever.
Where to go next
The AI pie chart generator will turn a small table of counts into slices. Glance at the total in the editor before you export, and the cheat sheet has the pie title line. The survey pie template is a second example, with answers instead of ticket types.
When the slices stop helping
A pie chart with more than six slices turns into a legend people do not read. Merge the tail into "Other" and say what you merged in the sentence under the figure. If the numbers are a time series, this is the wrong chart: move them to an XY chart. If they are a flow from one stage to the next, a Sankey keeps the order that a pie throws away.
Show the values with showData when the reader will quote a number in a meeting. A slice without a number invites someone to measure it with a ruler.
Tips and best practices
- Limit pies to about six slices; group the rest into Other.
- Order slices from largest to smallest for easier comparison.
- Use a bar chart (xychart) instead when you need to compare many similar values.
Generate a pie chart with AI
Not sure where to start? Describe what you need and the AI pie chart generator writes the Mermaid code for you. Try prompts like:
- “Time spent per activity in a typical work week”
- “Market share of cloud providers”
- “Household monthly expenses”
Pie Chart templates
Pie Chart FAQ
Do the values in a Mermaid pie chart have to add up to 100?
No. Mermaid sums all values and converts each slice to a percentage automatically.
How do I show the numbers on a Mermaid pie chart?
Write pie showData on the first line to display the raw values next to each label in the legend.
Can I change pie slice colors?
Yes, through theme variables such as pie1, pie2 … in an init directive or by choosing a different Mermaid theme in the editor.