Donut chart

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/donut-chart
• Markdown: https://ui.xzero.co.uk/components/donut-chart/markdown
• Registry item: https://mcp.xzero.co.uk/r/donut-chart.json
• Source file: registry/components/donut-chart/donut-chart.tsx
• Dependencies: motion
• Keywords: data, new, react donut chart, pie chart, ring chart, share of total chart, animated donut, chart with legend, category breakdown, accessible pie chart

When to use

• Traffic by source, spend by category, or storage by file type.
• A dashboard card where the total and one highlighted share matter most.
• Switching between datasets, such as this month and last month, with the same categories.

When not to use

• Use bar-chart when precise comparison between parts matters or there are many parts.
• Use gauge or usage-meter for a single value against a limit.
• Use line-chart for change over time.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/donut-chart

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { DonutChart } from "@/components/xzero/donut-chart/donut-chart";

export function TrafficSources() {
  return (
    <DonutChart
      label="Visits by source"
      unit="visits"
      data={[
        { key: "search", label: "Search", value: 4210 },
        { key: "direct", label: "Direct", value: 2380 },
        { key: "social", label: "Social", value: 1190 },
        { key: "email", label: "Email", value: 640 },
        { key: "ads", label: "Ads", value: 120 },
        { key: "other", label: "Referral", value: 90 },
      ]}
    />
  );
}

API reference

DonutChart

A donut chart with a synced legend that shows and hides segments, a rolling center readout, automatic Other grouping, and arcs that morph between datasets.

Prop	Type	Default	Description
data (required)	DonutChartDatum[]	–	Parts: { key, label, value, color? }. Values of zero or less are left out.
label (required)	string	–	What the whole is, such as "Visits by source". Names the chart for assistive technology.
unit	string	""	Unit after values, such as "visits". Shown under the total at rest.
formatValue	(value: number) => string	grouped number	Formats values in the center, legend, and table.
totalLabel	string	"Total"	Center label at rest, above the total.
size	number	208	Diameter in pixels. The chart scales down to fit narrower containers.
thickness	number	24	Ring thickness in pixels.
groupBelow	number	0.04	Parts below this share of the total join Other, when at least two would.
maxSegments	number	6	The most segments drawn, counting Other. The smallest parts beyond it are grouped.
otherLabel	string	"Other"	Label of the grouped segment.
activeKey	string | null	–	Controlled selected segment key. Hover and focus preview other segments without changing it.
defaultActiveKey	string | null	null	Selected segment on first render when uncontrolled.
onActiveChange	(key: string | null) => void	–	Called when a segment is pinned or unpinned by clicking the ring, or a legend row when legendAction is select.
hiddenKeys	string[]	–	Controlled hidden segment keys. A hidden segment closes and the rest of the ring redistributes.
defaultHiddenKeys	string[]	[]	Hidden segments on first render when uncontrolled.
onHiddenKeysChange	(keys: string[]) => void	–	Called when a legend row shows or hides its segment.
legendAction	"toggle" | "select"	"toggle"	What clicking a legend row does: show or hide its segment, or pin it as the selected segment.
legend	boolean	true	The synced legend beside or below the ring.
emptyLabel	string	"No data yet"	Center text when the total is zero.
ref	Ref<HTMLElement>	–	The figure element.
className	string	–	Class on the figure.

Keyboard interactions

Keys	Action
ArrowDown / ArrowRight	Moves to the next legend row, looping at the end.
ArrowUp / ArrowLeft	Moves to the previous legend row.
Home / End	Jumps to the first or last row.
Enter / Space	Shows or hides the focused segment; with legendAction select, pins or unpins it.
Escape	Clears the pinned segment.
Arrow keys on the ring	Without a legend the ring takes focus: arrows walk the segments, Enter pins one, and each is announced.

Accessibility

• The legend is the keyboard path: each row is a button with aria-pressed (shown, or pinned with legendAction select) and a label giving value, share, and grouped members.
• Showing or hiding a segment is announced in a polite live region with the new total. Without a legend the ring is focusable and announces each segment as the arrows reach it.
• The ring and center readout are aria-hidden; a hidden summary and table list every part, including the members of Other.
• Keyboard focus previews a segment in the ring; hover previews with a mouse only. Pointer focus draws no ring; keyboard focus shows Xzero's shared focus ring.

Motion

• One sweep the first time the chart scrolls into view: every segment leaves the top together and each trailing edge follows a beat behind the one before.
• New data and hidden segments morph start and end angles, never paths, from wherever each arc is on screen. Springs keep their velocity, so an interrupted change continues smoothly. Segments keep their order and never remount mid-morph.
• The active segment slides out along its middle and thickens slightly while the others dim. One pointer handler hit-tests the angle, so crossing a gap never drops the hover.
• The center readout rolls like a drum toward the active segment with tabular numbers in a fixed cell; totals and shares count to new values.
• Reduced motion jumps arcs, lifts, and text to their final state.

Responsive behavior

• The figure is a container: at 460px and wider the legend sits beside the ring, below that it stacks under it.
• The ring scales down from size to fit narrower containers while keeping its aspect ratio.
• Legend hover styles only apply on hover-capable fine pointers; taps pin a segment.

Performance

• Xzero angles and lifts are motion values; one batched paint per frame writes every path d and transform straight to the DOM, with no React render per frame.
• Counting numbers write their text directly; center readouts stay mounted, so hovering never mounts or unmounts nodes.

Notes for AI

• Use for two to six parts of one whole. With more parts, lean on groupBelow and maxSegments or use bar-chart.
• Keep keys stable between datasets so arcs morph in place.
• Leave color out to get the shared --series-1 to --series-4 palette in data order, then neutral steps; a key keeps its color across datasets. Pass colors only when they carry meaning.
• Legend rows show and hide segments by default; set legendAction to select for the older pin behavior.
• Drive activeKey from a table or filter to highlight the same category elsewhere.

Related

• Bar chart: Compare one measure across days and scrub any bar for its value.
• Line chart: A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
• Gauge: Show a value against a known range.
• Usage meter: Show what fills an allowance and how close it is to the limit.

Also in charts

• Streamgraph: Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
• Brush chart: A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
• Waffle chart: A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
• Slope chart: Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
• Sparkline: Show a compact trend beside a value.
• Activity heatmap: See a year of activity at a glance, one square per day.
• Animated counter: Give changing totals a clear sense of movement.
• Ridgeline: Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
• Treemap: A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
• Split bar: A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

Guidance for AI tools

Donut chart: A donut whose arcs morph between datasets, with the active value rolling into the center. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt