Donut (S2)

Pre-alpha component

Donut is a pre-alpha component — it has no finalized Spectrum 2 design yet and is imported from the pre-alpha subpath.

The Donut component displays a donut (or pie, via holeRatio={0}) chart. Each data point becomes a segment sized by metric and colored by color.

import { Chart, Legend } from '@spectrum-charts/react-spectrum-charts-s2';
import { Donut, DonutSummary, SegmentLabel } from '@spectrum-charts/react-spectrum-charts-s2/pre-alpha';

<Chart data={data}>
  <Donut metric="count" color="browser" />
  <Legend title="Browsers" position="right" highlight isToggleable />
</Chart>

---

Tooltips and popovers

Donut supports ChartInspect and ChartPopover like other S2 chart mark components. Unlike the base package, S2 does not have a ChartTooltip component — use ChartInspect instead.

Inside a Donut, both render default content without children: the segment's color swatch and series name, followed by its share of the visible total and short-number value (e.g. 65.2% (23K)), formatted with the chart locale. When children are provided, their content replaces the default content.

<Donut metric="count" color="browser">
  <ChartInspect />
  <ChartPopover width="auto">
    {(datum) => (
      <div>
        {datum.browser}: {datum.count} visitors
      </div>
    )}
  </ChartPopover>
</Donut>

---

Center summary (DonutSummary)

The DonutSummary component displays a label and aggregate value in the center of the donut. If isBoolean is set on the parent Donut, the summary shows the first data point's value as a percentage instead of a sum.

<Donut metric="count" color="browser" holeRatio={0.8}>
  <DonutSummary label="Visitors" />
</Donut>

DonutSummary props

name	type	default	description
hideValue	boolean	false	Hides the value portion of the summary, only showing the label.
label	string	–	Label displayed under the summary value.
numberFormat	string	'shortNumber'	A d3-format specifier for the summary value.

---

Segment labels (SegmentLabel)

The SegmentLabel component labels each donut segment directly, with its percentage and/or metric value.

<Donut metric="count" color="browser">
  <SegmentLabel percent />
</Donut>

Labels stay fixed at each segment's midpoint. A label is hidden when it would overlap a label for a larger segment, or when its segment is narrower than 0.3 radians (about 17°). Hovering a segment always shows its label and temporarily hides any labels that would overlap it.

When emphasizedItems is set, two SegmentLabel children can provide different label treatments for emphasized and de-emphasized segments:

<Donut metric="count" color="browser" emphasizedItems={['Chrome']}>
  <SegmentLabel labelMode="emphasized" swatch showValueRow />
  <SegmentLabel labelMode="deemphasized" value />
</Donut>

SegmentLabel props

name	type	default	description
labelMode	'emphasized' | 'deemphasized'	–	Selects which emphasized segment group receives this label. Omit for uniform single-label behavior.
showValueRow	boolean	false	Shows an additional segment value row.
showTotal	boolean	false	Appends / total to the segment value row.
labelKey	string	(the parent Donut's color field)	Key in the data that has the segment label.
percent	boolean	false	Shows the donut segment's percentage of the total.
percentFormat	string	'.0%'	A d3-format specifier for the percentage value.
swatch	boolean	false	Shows a color swatch before the segment label.
value	boolean	true	Shows the donut segment's metric value.
valueFormat	string	'standardNumber'	A d3-format specifier for the metric value.

---

Boolean donuts

When isBoolean is set, the data should be exactly two points that sum to 1 — the first point is displayed as a percent of the whole (e.g. a success/failure rate):

<Donut metric="value" color="id" isBoolean colors={['green-800', 'gray-200']}>
  <DonutSummary label="Success rate" />
</Donut>

---

Semicircle donuts

Setting variant="semicircle" renders a top-half arc instead of a full circle. By default, data is sorted descending by metric, so the largest segment renders leftmost. Set sortOrder="data" to preserve source order for ordinal categories. Semicircles start at 9 o'clock and sweep clockwise through 12 to 3 o'clock. Circle donuts start at 12 o'clock. These start positions are fixed.

<Donut metric="count" color="browser" variant="semicircle">
  <DonutSummary label="Visitors" />
</Donut>

<Donut metric="count" color="response" variant="semicircle" sortOrder="data">
  <DonutSummary label="Responses" />
</Donut>

Segment labels unsupported

SegmentLabel children are not supported for variant="semicircle" and are silently omitted.

---

Donut props (S2)

name	type	default	description
children	ChartInspect | ChartPopover | DonutSummary | SegmentLabel	–	Optional child components for inspect panels, popovers, a center summary, and segment labels.
color	string	'series'	Key in the data used to map each segment to a color.
emphasizedItems	(string | number)[]	–	Segments whose categorical colors remain emphasized. Other segments use gray-400.
hideDeemphasizedLabels	boolean	false	Hides labels for segments outside emphasizedItems.
holeRatio	number	0.85	Ratio of the donut's inner radius to its outer radius. 0 renders a pie chart.
isBoolean	boolean	false	Treats the data as a two-point boolean pair summing to 1, displaying the first point as a percent of the whole.
metric	string	'value'	Key in the data used to size each segment.
name	string	–	Name of the donut component. Useful when referencing the donut marks programmatically.
sortOrder	'valueDescending' | 'data'	'valueDescending'	Controls semicircle segment ordering. 'data' preserves source order for ordinal categories.
variant	'circle' | 'semicircle'	'circle'	Renders a top-half arc instead of a full circle. SegmentLabel children are not supported with this variant.