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.

Interactive donut segments and their direct or advanced labels animate opacity on hover. Legend hover, controlled highlights, and popover selection share the animation state. Set animations={false} or animationTypes={[]} on Chart to keep instant opacity changes instead. A donut without interactive children or highlighting remains static.

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>

Draw-in animation

Add 'drawIn' to the chart's animationTypes to sweep the segments clockwise over one second with a quadratic ease-in. Full-circle donuts and pies start at the top; semicircle donuts start at the left. Direct and advanced labels start a 50ms linear fade as soon as their own slice finishes drawing. All text rows and swatches fade together; the final label finishes about 50ms after the donut. Hover dimming and existing small-segment and collision rules still apply. The center summary stays visible throughout.

<Chart data={data} animationTypes={['hover', 'drawIn']}>
  <Donut metric="count" color="browser">
    <SegmentLabel value />
  </Donut>
</Chart>

Draw-in is off by default. animations={false} disables it even when 'drawIn' is listed. It runs when the Vega view is created, including after data or spec changes; resizing an existing view does not replay it. Empty-state rings remain static.

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.

Tooltips and popovers​

Draw-in animation​

Center summary (DonutSummary)​

DonutSummary props​

Segment labels (SegmentLabel)​

SegmentLabel props​

Boolean donuts​

Semicircle donuts​

Donut props (S2)​