Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 44 ยท Shapes and Paths

Pie and Donut Charts with d3.pie and d3.arc

Build pie, donut and radial charts with d3.pie and d3.arc: angles, innerRadius and outerRadius, padAngle, cornerRadius, centroid labels.

Pie and donut charts show parts of a whole as angles. They are controversial among chart designers (angles are harder to compare than lengths), but they are common, familiar, and a perfect way to learn two D3 generators that work together: d3.pie() computes the angles, and d3.arc() turns each angle into an SVG path.

Two generators, two jobs

  • d3.pie() takes your data and returns one object per datum with startAngle, endAngle, padAngle, value and index, plus the original item as .data. It does no drawing.
  • d3.arc() takes such an object (or any object with those angle properties) and returns a path string for a ring segment with inner and outer radius.

Angles are in radians measured clockwise from 12 o'clock, so a full circle is 2ฯ€ (about 6.283).

JavaScript
const pie = d3.pie().value(d => d.share);
const arcs = pie(data);          // array of {data, value, startAngle, endAngle, ...}

const arc = d3.arc().innerRadius(0).outerRadius(120);
arc(arcs[0]);                    // "M0,-120A120,120,0,0,1,..."
What d3.pie computes

By default d3.pie() sorts slices by value, largest first. Call .sort(null) to keep the input order, or .sort((a, b) => a.name.localeCompare(b.name)) to sort by your own rule. The index property remembers the original position.

Drawing the chart

Pie charts are centered at the origin, so place a g at the middle of the SVG and draw into it.

A pie chart with labels and a legend

Notes on the code:

  • .attr("d", arc) works because D3 calls arc(d, i) for each slice; arc reads startAngle and endAngle from the pie output.
  • Small slices get no label (a filter) because text would not fit.
  • arc.centroid(d) returns the [x, y] center of a slice, and using a second arc generator with a different radius puts labels where you want them.

From pie to donut

A donut is a pie with an inner radius greater than zero. The empty center is a natural place for a total or a headline number, and the shape gives slightly more room for labels.

JavaScript
const arc = d3.arc()
  .innerRadius(radius * 0.6)
  .outerRadius(radius)
  .padAngle(0.02)           // small gap between slices (radians)
  .cornerRadius(4);         // rounded corners

d3.pie().padAngle(0.02) can also set the pad angle on the pie output.

A donut with center text and padding

Half circles and gauges

You can limit the sweep with pie.startAngle() and pie.endAngle() (in radians). A half-circle gauge uses -Math.PI / 2 to Math.PI / 2. The same idea gives a progress ring: draw a gray full ring, then an arc from 0 to value * 2 * Math.PI on top.

Outside labels and leader lines

For many slices, labels fit better outside. Compute the label position from a larger arc's centroid and align by side:

JavaScript
const outer = d3.arc().innerRadius(radius * 1.1).outerRadius(radius * 1.1);
const midAngle = d => (d.startAngle + d.endAngle) / 2;

labels
  .attr("transform", d => `translate(${outer.centroid(d)})`)
  .attr("text-anchor", d => midAngle(d) < Math.PI ? "start" : "end");

Slices on the right half (angle below ฯ€) are anchored at the start so text flows away from the pie; those on the left are anchored at the end.

When not to use a pie

  • More than five or six categories: slices become slivers.
  • Comparing values that are close: bars show lengths far more accurately than angles.
  • Comparing across several pies: use small multiples of bars or a stacked bar.
  • Values that are not parts of a whole.

If you must use a pie, order slices by size, start at 12 o'clock, limit categories (group the tail into "Other"), and label directly.

d3.arc() is not only for pies. With your own startAngle and endAngle it draws sunburst partitions, radial bar charts and gauges, as you will see in the layout chapter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does d3.pie() return?

    d3.pie only computes angles. d3.arc turns each result into a path string.
  2. 2. How are angles measured by d3.pie and d3.arc?

    Both use radians with zero at the top, increasing clockwise.
  3. 3. How do you turn a pie into a donut?

    A donut is an arc with a positive inner radius.
  4. 4. What does arc.centroid(d) give you?

    The centroid is the midpoint between the inner and outer radius at the mid-angle of the arc.

Summary

  • d3.pie() computes angles (radians, clockwise from the top); d3.arc() converts them into path strings.
  • Draw into a g translated to the center; use sort(null) to keep input order and padAngle for gaps.
  • A donut is an arc with innerRadius > 0; use centroid or a bigger arc for label positions.
  • Pies suit few categories; prefer bars when comparing values precisely.

Next: Scatter Plots, Bubble Charts and Symbols