Skip to main content

Mermaid 11.15.0

Mermaid pie chart cheat sheet

Pie charts compare a few positive parts of one total. Choose a bar chart for many categories or close values, and a quadrant chart for comparing two independent dimensions.

Build this in Pie Chart Maker →

Quick start

Values are weights, not percentages that must add to 100. Mermaid calculates each share of the total.

Mermaid
Open in editor → 
pie showData
  title Documentation effort
  "Writing" : 48
  "Review" : 32
  "Publishing" : 20

Loading…

Syntax reference

Syntax reference
SyntaxMeaning
pie / pie showDataDeclare a pie chart; showData adds raw values to the legend.
title TextAdd an optional heading.
"Label" : 12.75Use quoted labels and positive numeric weights. Two decimal places are the documented precision.
config.pie.textPosition: 0.75Place slice text radially: 0 is the center, 1 is the outer edge.
themeVariables.pieOuterStrokeWidth: "2px"Set the width of the chart’s outer border.
themeVariables.pie1…pie12Set the palette’s slice colors using the base theme.
pieTitleTextSize / pieTitleTextColor / pieSectionTextSize / pieSectionTextColorTheme variables for the heading and slice labels.
pieLegendTextSize / pieLegendTextColor / pieStrokeColor / pieStrokeWidth / pieOuterStrokeColor / pieOpacityTheme variables for legend text, slice borders, outer border and opacity.
%% / accTitle: / accDescr:Add comments and accessible descriptions.

Decimals and proportional shares

Keep source values positive. Use a dot as the decimal separator, even in languages that normally display a comma. showData displays the supplied weights in the legend; slice labels round percentages to whole numbers. In Mermaid 11.15, slices below 1% are hidden, although their legend entries remain.

Mermaid
Open in editor → 
pie showData
  title Editing hours
  "Drafting" : 12.75
  "Fact checking" : 6.25
  "Proofreading" : 3.50

Loading…

Labels and a compact legend

Keep category names short so the legend remains readable. Without showData, the legend lists the names while slice text still represents proportions. Avoid many tiny categories.

Mermaid
Open in editor → 
pie
  title Review outcomes
  "Accepted" : 18
  "Revised" : 7
  "Deferred" : 3

Loading…

Moving slice text inward

TextPosition is a radial ratio, not a pixel distance. A smaller value moves labels toward the center. Very narrow slices can still overlap; simplify the data before adjusting appearance.

Mermaid
Open in editor → 
---
config:
  pie:
    textPosition: 0.6
---
pie showData
  title Review split
  "Technical" : 60
  "Editorial" : 40

Loading…

Slice colors and outer border

Use theme base before customizing pie1 through pie12. Set pieOuterStrokeWidth as a CSS length. Match text and border colors to the background; the palette does not make closely sized slices easier to compare.

Mermaid
Open in editor → 
---
config:
  theme: base
  themeVariables:
    pie1: "#d3e5ff"
    pie2: "#50e3c2"
    pie3: "#f5f5f5"
    pieOuterStrokeWidth: "2px"
    pieSectionTextColor: "#171717"
---
pie showData
  title Work allocation
  "Research" : 45
  "Writing" : 35
  "Review" : 20

Loading…

Common mistakes

Using a negative weight

Negative numbers are rejected. Use a positive value; a pie cannot represent a net loss.

Invalid syntax — corrected example below

pie
  "Review" : -2

Using a comma as a decimal separator

Write 12.75, not 12,75. Round source data to two decimal places for the documented notation.

Limitations

  • Use positive weights for visible slices. Zero is accepted but draws no slice; negative values are rejected.
  • Two decimal places are documented for source values, but percentage labels round to whole numbers. Slices below 1% are hidden.
  • Many categories and close values are difficult to compare visually; prefer a bar chart.

Frequently Asked Questions

Must the values add to 100?
No. Mermaid divides each positive weight by their total to compute the shares.
What does showData change?
It adds the supplied numeric values to the legend; it does not change the weights or the chart geometry.
How do I change the slice colors?
Use theme base and set pie1 through pie12 in themeVariables.