Visualizing metrics with Mermaid pie and bar chart diagrams

Not every diagram is a flowchart or a sequence. Sometimes you just need to show proportions, distributions, or simple trends—and Mermaid's pie and bar chart types let you do that in plain text, without reaching for a separate charting library.

When to use pie and bar charts in Mermaid

Pie charts excel at showing composition—what fraction of your system is which component:

• Cloud cost breakdown (35% compute, 40% storage, 25% networking)
• Sprint capacity (50% feature work, 30% bugs, 20% tech debt)
• Customer distribution by region or cohort

Bar charts work better for comparisons and trends:

• Metrics across teams or releases (bugs found, tickets closed, deployment frequency)
• Before/after comparisons (latency improvement, error rate reduction)
• Rankings (most-used APIs, slowest endpoints)

The advantage over static images: your diagrams live in version control and render anywhere Mermaid works—GitHub, Slack, wikis, docs.

Pie chart syntax and examples

The simplest chart syntax in Mermaid:

pie title Development Time Allocation
    "Frontend Development" : 35
    "Backend APIs" : 30
    "Testing" : 20
    "DevOps & Infra" : 15

Parse it step by step:

• pie title <Title> — Start a pie chart and set the title.
• "<Label>" : <Percentage> — Each line is one slice. Values are relative (Mermaid normalizes them), so 35 + 30 + 20 + 15 = 100 or any total.

You don't need percentages to sum to 100; Mermaid auto-scales:

pie title Memory Usage by Service
    "API Gateway" : 256
    "User Service" : 512
    "Order Service" : 384
    "Cache (Redis)" : 1024
    "Database" : 2048

Here, the values are megabytes. Mermaid computes the percentages: Redis uses ~29% of the total, Database uses ~58%, etc.

Example: Feature request breakdown by category

pie title Feature Requests (Q2 2026)
    "UI Enhancements" : 42
    "Performance" : 28
    "Security" : 18
    "Integrations" : 12

Bar chart syntax and examples

Bar charts (sometimes called "statistics" in Mermaid docs) show side-by-side comparisons:

---
config:
    xyChart:
        width: 900
        height: 600
    themeVariables:
        xyChart:
            plotColorPalette: "#2196F3, #4CAF50"
---
xychart-beta
    title "API Response Time by Endpoint (ms)"
    x-axis [GET /users, GET /posts, POST /comments, DELETE /cache]
    y-axis "Response Time (ms)" 0 --> 300
    line [45, 120, 89, 230]
    line [52, 118, 91, 225]

This is more advanced, but for simple bar comparisons, use a table-based format within a note or comment. However, for cleaner bar visualization, use the xychart-beta syntax (currently in beta):

xychart-beta
    title "Test Coverage by Module (%)"
    x-axis [Core, Auth, API, UI, Utils]
    y-axis "Coverage" 0 --> 100
    bar [95, 87, 72, 63, 91]

The xychart-beta syntax supports:

• x-axis — Labels for each bar or category.
• y-axis "<label>" <min> --> <max> — Y-axis range and label.
• bar [<val1>, <val2>, ...] — One bar per x value.
• line [...] — Overlay a trend line (handy for before/after).

Realistic example: Sprint metrics dashboard

pie title Sprint Capacity Utilization (Aug 2026)
    "Planned Features" : 45
    "Bug Fixes" : 25
    "Tech Debt" : 20
    "Unplanned Interrupts" : 10

And the trend across sprints:

xychart-beta
    title "Bugs Closed per Sprint"
    x-axis [Sprint 1, Sprint 2, Sprint 3, Sprint 4, Sprint 5]
    y-axis "Bugs Closed" 0 --> 50
    bar [28, 34, 31, 42, 39]
    line [28, 34, 31, 42, 39]

Cost breakdown example

A classic use case for pie charts—cloud cost allocation:

pie title AWS Monthly Cost ($8,500 total)
    "Compute (EC2, ECS)" : 3200
    "Storage (S3, RDS)" : 2800
    "Data Transfer" : 1200
    "Other Services" : 1300

Embed this in your monthly budget doc to make spend visible at a glance.

Limitations and workarounds

Mermaid charts are simple. You won't get logarithmic scales, overlapping error bars, or heatmaps. For complex financial or scientific visualization, stick with D3, Plotly, or similar.

No interactivity. Charts render as static SVG. You can't hover for tooltips or drill down.

Pie charts don't work well with >5 slices. Beyond that, labels collide and percentages become hard to read. If you have 10+ categories, use a bar chart instead or group small slices into "Other".

Bar charts in beta. The xychart-beta syntax may change. For production docs, test locally and render to PNG if you need long-term stability.

When to inline a chart vs. a separate diagram

• Inline (in a README, docs, or PR): Small pie charts showing a snapshot (sprint allocation, cost breakdown). Readers want context without leaving the page.
• Separate file: Complex multi-series charts or dashboards. Use the editor to draft and iterate.

Comparison: Mermaid charts vs. images vs. tables

Format	Pros	Cons	Best For
Mermaid Pie	Version-controlled, text-based, renders everywhere	Limited styling, no interactivity	Simple proportions
Mermaid Bar	Trend-friendly, clean defaults	Beta status, basic only	Sprint/performance metrics
PNG/JPEG	Pixel-perfect, fast render	Unmaintainable, diffs are useless, outdates quickly	Finished reports, marketing
Table	Exact numbers, reviewable in diffs	Not visual, hard to spot trends	Detailed data, precise citations

For development docs, Mermaid charts beat images every time—they live in git, change in reviews, and don't rot.

FAQ

Q: Can I export a pie chart as an image? A: Yes. Most Mermaid renderers (including the MermaidCreator playground) offer a download-as-PNG option.

Q: How do I animate values over time? A: Mermaid doesn't support animation natively. Create multiple diagrams (one per time period) and link them, or use a bar chart to show the trend as a single view.

Q: Can I use floating-point percentages? A: Yes, though Mermaid normalizes them. 35.5, 30.2, etc., work fine.

Q: Does Mermaid support stacked bar charts? A: Not yet in the stable syntax. For that level of detail, switch to a dedicated charting library.

---

For a hands-on experience, draft a pie or bar chart in the MermaidCreator editor and see how easy it is to update and share.