Mermaid Pie Charts for Data Visualization
Create pie charts with Mermaid to visualize data distributions. Learn the simple pie chart syntax, add titles, and represent proportional data in documentation.
Detailed Explanation
Pie Charts in Mermaid
Pie charts are the simplest Mermaid diagram type. They display proportional data as slices of a circle, making them perfect for showing distributions, market shares, or resource allocations in documentation.
Basic Syntax
pie title Language Distribution
"JavaScript" : 45
"TypeScript" : 30
"Python" : 15
"Other" : 10
Each entry is a quoted label followed by a colon and a numeric value. Mermaid automatically calculates percentages and assigns colors.
How Values Work
Values are relative, not absolute percentages. Mermaid sums all values and calculates each slice as a proportion of the total. These two charts render identically:
pie title Budget Allocation
"Engineering" : 50
"Marketing" : 30
"Operations" : 20
pie title Budget Allocation
"Engineering" : 5
"Marketing" : 3
"Operations" : 2
Adding a Title
The title keyword after pie sets the chart heading. It appears centered above the chart:
pie showData title Error Distribution (Q4 2024)
"Timeout" : 42
"4xx Client" : 28
"5xx Server" : 18
"Network" : 12
The showData keyword adds percentage labels to each slice, improving readability.
Best Practices
- Limit to 5-7 slices — too many slices make the chart hard to read. Group small categories into "Other."
- Order slices by size — list the largest slice first for a cleaner visual.
- Use descriptive labels — "Timeout Errors (42%)" is more informative than "Type A."
- Pair with a table — for precise data, include a Markdown table alongside the chart since pie charts are approximate by nature.
When to Use Pie Charts
Pie charts work well for:
- Showing how parts make up a whole (e.g., test coverage by module)
- Comparing a small number of categories
- Quick visual summaries in README files and reports
They are not ideal for comparing values across time (use Gantt or timeline) or showing exact differences between similar values (use a table instead).
Use Case
A DevOps team adding a visual breakdown of production error types to their post-incident report. The pie chart shows that 42% of errors were timeouts, immediately highlighting where reliability efforts should focus.