Donut chart

Circular part-to-whole chart with a central label slot.

donut is a pie chart with the centre removed, opening a slot for a total, key metric, or icon. See Properties for every key it accepts.

When to use

• Same situations as a pie chart, but where a central metric adds context (total value, share of target, KPI badge)
• Editorial layouts where the modern aesthetic suits the surrounding design
• When arc length needs to read slightly more cleanly than wedge area

When NOT to use

• More than 5–6 slices — use sliceMax to merge the tail into "Other"
• Comparing several donut charts against each other (small multiples of bar charts win)
• When precise value reading matters

Example

chart donut {
  title = "Coal still generates a third of the world's electricity"
  description = "Share by source, 2024"
  source = "IEA"
  sourceUrl = "https://iea.org"
  byline = "Pierre Romera"
  note = "Percentages may not sum to 100 due to rounding"
  colors = "#76b7b2, #4e79a7, #59a14f, #f28e2b, #edc949, #e15759, #b07aa1"
  legendPosition = "right"
  tooltips = true
  displayAsPercentage = true

  data {
    "Coal" = 34.2
    "Natural Gas" = 22.1
    "Hydro" = 14.8
    "Nuclear" = 9.4
    "Wind" = 9.5
    "Solar" = 6.2
    "Other" = 3.8
  }
}

Properties

Every property donut accepts, beside the frame and layout keys every chart shares. Anything absent from this table is rejected by validateChart and ignored by the renderer.

Property	Type	Default
colors	colors	(unset)
colorPalette	select, see Palettes	Blueprint
autoContrast	boolean	false
allowDarkMode	boolean	true
legend	boolean	false
legendAnchor	select: start, middle, end	start
legendPosition	select: top, bottom, left, right	top
directLabelling	select: "", auto, outside, inside	auto
tooltips	boolean	false
displayAsPercentage	boolean	false
showTotal	boolean	true
showLabels	boolean	true
showValues	boolean	true
sliceMax	text	6
sliceGroupLabel	text	Others

Common pitfalls

• Filling the centre slot with decoration instead of a meaningful metric wastes the chart's main affordance
• Inner radius too thin reads like a pie; too thick collapses the ring into a stripe
• Same caveats as a pie: too many slices, similar sizes, and side-by-side comparisons all hurt readability

Related types

• pie — when there's no central metric worth showing
• bar-horizontal — when precise comparison matters
• bar-stacked — composition across several totals

See also

• Choosing the right chart
• Design principles