Mermaid Pie Chart Tutorial: Proportion Charts from a Few Lines of Text
The Mermaid pie chart is the simplest data diagram in the language - a title and a handful of label-value pairs - but choosing when to use one is where the real skill lies.
The pie chart is the most familiar data visualization there is, and Mermaid makes one from about the least syntax of any diagram type: a keyword, an optional title, and a list of labels with their values. Mermaid computes the percentages and draws the slices for you, so a breakdown of a budget or a market share split is a few lines of text. The catch is not the syntax but the judgment - pie charts are widely overused, and knowing when one actually communicates well is what separates a clear chart from a confusing one.
This guide covers the pie syntax quickly and then spends its energy on that judgment, with examples for the Mermaid editor at /diagram-tools/mermaid-editor. The rendered pie is editable in Atlas Diagram Studio at /diagrams, ready for a report or slide. When a pie is the wrong fit, Mermaid's xychart-beta bar chart is usually the better tool, and the AI diagram generator at /diagram-tools/ai-diagram-generator can draft whichever you describe so you can compare them side by side.
The pie syntax
A pie chart is declared with the keyword "pie", optionally followed on the same line by "showData" to display the raw numbers alongside the percentages. A "title" line names the chart. The data is then one label-value pair per line: a quoted label, a colon, and a number, as in '"Engineering" : 45'. That is the entire language - Mermaid sums the values, converts each to a percentage of the whole, and draws the slices in order.
You do not provide percentages; you provide raw values and Mermaid does the arithmetic, which means the numbers do not need to add to 100. If your values are 45, 30, and 25 they happen to total 100, but 450, 300, and 250 would produce the identical chart because only the proportions matter. Adding "showData" is helpful when readers want the actual figures and not just the relative sizes, since a slice's angle alone does not reveal the underlying number.
The complete option set
Pie is deliberately minimal, so the full set of things you can control is short. The bullets below cover all of it, plus the practical habits that make a pie readable.
- Declare the chart with "pie", or "pie showData" to print the raw values on the slices.
- Add a 'title "Budget Allocation"' line to name the chart.
- Write each slice as a quoted label, a colon, and a value: '"Marketing" : 30'.
- Provide raw values, not percentages - Mermaid computes the proportions itself.
- Values need not sum to 100, since only their relative sizes determine the slices.
- Order slices largest to smallest so the chart reads cleanly from the top.
- Keep the number of slices small - a handful, not a dozen - so each remains distinguishable.
When a pie chart actually works
Pie charts communicate one thing well: the parts of a single whole, when there are only a few parts and one or two clearly dominate. "Sixty percent of the budget goes to engineering" is a message a pie lands instantly. Where pies fail is comparison - the human eye is poor at judging the relative size of similar slices, so a pie with five near-equal segments forces the reader to squint and guess. It also cannot show change over time or across categories, because a pie is a single snapshot of one whole.
The honest test before using a pie is to ask whether a reader could rank the slices at a glance. If two slices are close in size, a pie hides the difference that a bar chart would make obvious, since bars share a common baseline the eye can compare precisely. When the data is really a comparison of quantities rather than a part-to-whole story, an xychart-beta bar chart communicates better, and it is barely more syntax. Use the pie for genuine part-of-a-whole breakdowns with a small number of dominant slices, and reach for bars for everything else.
Fitting the pie into a report
Because a pie is so quick to write, it is easy to keep current in a living report - update a value and the slices recompute. That makes it a good fit for recurring status documents where a single breakdown appears each cycle. Author it in the Mermaid editor at /diagram-tools/mermaid-editor, style and brand it in Atlas Diagram Studio at /diagrams, and keep the source next to the document so the chart versions with the rest.
Pair it thoughtfully with other data diagrams: a pie for the current split, an xychart line for the trend over time, and a sankey-beta when the whole flows and splits across stages. Choosing the right one for each message is the skill, and the complete Mermaid guide at /guides/mermaid-js-complete-guide lays out the full set of data-oriented diagrams so you can pick deliberately. The guide on turning plain English into diagrams at /guides/text-to-diagram-with-ai covers generating any of them from a prompt.