Mermaid Pie Chart: Complete Syntax Guide with Examples

Mermaid pie charts let you embed distribution visualizations directly in Markdown files using plain text. Write the data once, commit it alongside your documentation, and every Mermaid-compatible renderer — GitHub, GitLab, Notion, or MacMD Viewer — displays a polished pie chart. No charting library, no spreadsheet, no image to update when the numbers change.

TL;DR: Start with pie, add title Your Title and slice definitions as "Label" : value. Use pie showData to display raw values alongside percentages. Keep slices to seven or fewer for readability. Preview locally with MacMD Viewer or online at mermaid.live.

What Are Mermaid Pie Charts For?

Mermaid pie charts are the right tool when you need to show part-of-whole relationships inside a Markdown document. They shine in READMEs showing how a codebase is split by language, project retrospectives breaking down time allocation by category, bug triage reports showing distribution by severity, and any documentation where a quick proportional snapshot adds more value than a table of numbers.

The format is intentionally minimal. Mermaid handles color assignment, percentage calculation, and layout automatically. You provide labels and raw values; the renderer does the rest. This constraint is also the chart's main limitation — there is no donut variant, no exploded slices, and no custom slice colors in the base syntax. For those needs you would reach for a dedicated charting tool. For embedded documentation, the simplicity is a feature.

Pie charts answer the question "what share does each part hold?" When you need to compare absolute quantities across categories instead, a bar chart or Mermaid's xychart type is a better fit. When you need to show change over time, use a line or xychart. Pie charts are specifically for proportional composition at a single point in time.

How Do You Write Basic Mermaid Pie Chart Syntax?

Every Mermaid pie chart starts with the keyword pie on its own line. A title is optional but strongly recommended — without it, readers have no context for what the proportions represent. Each slice is defined on its own line as "Label" : value.

pie title Browser Market Share 2024
    "Chrome" : 65.7
    "Safari" : 18.6
    "Firefox" : 3.2
    "Edge" : 5.1
    "Other" : 7.4

Breaking down each part:

• pie — the required declaration that tells Mermaid to render a pie chart
• title Browser Market Share 2024 — optional chart title, placed on the same line as pie or on the next line
• "Chrome" : 65.7 — a slice definition: label in double quotes, colon separator, numeric value

Values are relative proportions, not percentages. You do not need them to sum to 100. If you write "A" : 1 and "B" : 3, Mermaid renders A as 25% and B as 75%. You can use the raw counts from your data directly — no manual percentage calculation required.

The title can also go on a separate line immediately after pie:

pie
    title Project Time Allocation — Q1
    "Feature development" : 42
    "Bug fixes" : 23
    "Code review" : 18
    "Documentation" : 11
    "Meetings" : 6

Both formats are valid. The inline pie title ... form is more compact; the separate title line reads more clearly when the chart has many slices.

What Does the showData Option Do?

The showData keyword, placed on the same line as pie, adds raw numeric values to the legend alongside the auto-calculated percentage. Without showData, the legend shows only the label and its percentage share.

pie showData
    title Bug Reports by Type — March 2026
    "UI / Layout" : 34
    "Performance" : 21
    "Crash / Error" : 15
    "Data integrity" : 8
    "Accessibility" : 5
    "Other" : 4

With showData, the legend renders something like: UI / Layout [34] — 39.1%. This is useful when the raw count carries meaning beyond the proportion — for example, when reviewers need to see that "Crash / Error" had 15 reports, not just that it represents 17% of the total.

Use showData when your audience needs both the relative distribution and the absolute numbers. Omit it when proportions alone tell the story and adding raw values would clutter the legend.

Real-World Pie Chart Examples

Browser Market Share

pie title Browser Market Share 2024
    "Chrome" : 65.7
    "Safari" : 18.6
    "Firefox" : 3.2
    "Edge" : 5.1
    "Other" : 7.4

A classic use case: a quick proportional snapshot in a web analytics README or presentation note. The values come directly from raw data — no manual conversion to percentages needed.

Project Time Allocation

pie showData title Sprint 23 — Time Allocation
    "Feature development" : 42
    "Bug fixes" : 23
    "Code review" : 18
    "Documentation" : 11
    "Meetings" : 6

showData here lets stakeholders see both the proportions and the actual hours invested in each category. Useful in retrospective documents committed alongside the sprint's code.

Bug Distribution by Severity

pie title Open Bugs by Severity
    "Critical" : 4
    "High" : 12
    "Medium" : 31
    "Low" : 48
    "Informational" : 9

A triage snapshot in a project wiki. The proportions immediately show that the backlog is dominated by low and medium severity issues, which frames prioritization discussions without a separate dashboard.

What Are the Limitations of Mermaid Pie Charts?

Mermaid pie charts cover proportional visualization in documentation, but the syntax is deliberately constrained. Key limitations to be aware of:

No donut chart variant. There is no keyword to remove the center fill and produce a ring chart. If you need a donut, you would need to render the diagram outside Mermaid or use a custom SVG.

No custom slice colors. Colors are assigned automatically from the active Mermaid theme palette. You can change the overall theme using an %%{init}%% directive, but individual slice colors cannot be set in the basic syntax without CSS overrides — and those only work in environments that allow injecting custom stylesheets.

No interactive tooltips in static renders. In environments like GitHub, the rendered pie chart is a static SVG image. Hover tooltips that show label and value on mouse-over are available only in environments that run Mermaid's JavaScript renderer interactively, such as mermaid.live or MacMD Viewer.

No exploded slices. There is no way to visually separate a specific slice from the rest of the chart to draw emphasis.

Labels truncate on small slices. Slices that represent a very small percentage may have their labels overlap or be cut off, depending on the renderer. Keeping your dataset to seven or fewer categories significantly reduces this risk.

For production data visualizations or interactive dashboards, use a dedicated charting library. For embedded documentation — READMEs, wikis, architecture decision records — these constraints are rarely a problem.

Pie vs. Other Mermaid Chart Types: When Should You Use Each?

Choosing the right chart type shapes how quickly your audience understands the data. Here is a practical guide:

Use a pie chart when part-of-whole is the primary message and you have seven or fewer meaningful categories. Avoid pie charts when the differences between slices are small (adjacent slices of 18% and 22% are nearly impossible to distinguish visually) — a bar chart makes those differences immediately legible.

Where Does Mermaid Pie Chart Render?

Mermaid pie charts render in the following environments:

MacMD Viewer ($19.99 one-time — download) renders all Mermaid diagram types in local .md files on Mac. Open a file containing a pie chart and it appears instantly. The bundled QuickLook extension renders diagrams when you press Space on a .md file in Finder — no internet connection or browser extension required. To export a pie chart as a static image, use the Mermaid-to-PNG converter.

For a broader look at rendering options, see the Mermaid Live Editor guide.

Tips for Better Mermaid Pie Charts

Always include a title. A pie chart without a title forces readers to look at surrounding text to understand what the proportions represent. Put the context directly on the chart.

Keep slices to seven or fewer. Human perception struggles to compare more than seven arc segments simultaneously. If you have twelve categories, group the smallest into an "Other" slice. showData lets readers see the "Other" total and seek detail elsewhere if needed.

Use specific, descriptive labels. "Category A" and "Category B" convey nothing. "Bug fixes", "Feature dev", and "Maintenance" communicate immediately. Labels appear in the legend next to the percentage — they are your primary communication tool.

Use raw counts, not pre-calculated percentages. Mermaid computes percentages automatically. If you enter pre-calculated percentages that do not sum to exactly 100 due to rounding, the rendered chart will be proportionally incorrect. Enter your raw data and let Mermaid handle the math.

Validate syntax before committing. Paste your pie chart definition into mermaid.live or open the file in MacMD Viewer to confirm it renders correctly. A missing double quote or colon will silently produce an empty diagram on GitHub.

Conclusion

Mermaid pie chart syntax is deliberately simple: pie, an optional title, and one "Label" : value line per slice. Add showData when raw values matter alongside proportions. Keep slices to seven or fewer, use a title, and enter raw counts rather than pre-calculated percentages. The renderer handles color, layout, and percentage calculation automatically.

For other Mermaid diagram types, see the Mermaid flowchart syntax guide, the Mermaid Gantt chart guide, the Mermaid ER diagram guide, the Mermaid class diagram guide, and the Mermaid mindmap guide. To render all of these locally on Mac without a browser, MacMD Viewer ($19.99) opens any .md file and displays every Mermaid diagram type instantly.