DonutChart
Donut charts are for parts-to-whole comparison—how partial elements add up to a total—shown as a ring so a few categories are easy to compare at a glance.
Installation
npm install @godaddy/antaresProps
dataOptional<DonutSliceDatum, "id">[]—Slice definitions (`name`, `value`; `id` optional, auto-assigned like line/bar chart series).
labelstring—Primary label in the donut hole.
subLabel?string | undefined—Secondary label below the primary label.
legend?"bottom" | "right" | undefined—Where to render the legend relative to the chart. Leave unset for no legend.
legendLabel?string | undefined—Passed to Legend as `label` when legend is shown.
smallSliceThreshold?number | undefined0.05Share of total at or below which a slice is “small”; hovering a small slice shows that contiguous group of small neighbors on the ring (nearest run, wrapping at the first/last slice).
formatValue?((value: number) => string) | undefinedString(value)Formats slice values in the tooltip.
display?"flex" | "inline-flex" | undefined'flex'The display property for the flex container.
direction?"row" | "column" | "row-reverse" | "column-reverse" | undefined'row'The direction in which to layout children.
wrap?"wrap" | "nowrap" | "wrap-reverse" | undefined—Whether to wrap items onto multiple lines.
as?(React.ElementType & "div") | undefined'div'Polymorphic element type.
padding?Spacing | Spacing[] | undefined—Padding on all sides. Accepts single value or array.
inlinePadding?Spacing | Spacing[] | undefined—Padding on inline (horizontal) direction.
inlinePaddingStart?Spacing | undefined—Padding on inline start (left in LTR).
inlinePaddingEnd?Spacing | undefined—Padding on inline end (right in LTR).
blockPadding?Spacing | Spacing[] | undefined—Padding on block (vertical) direction.
blockPaddingStart?Spacing | undefined—Padding on block start (top).
blockPaddingEnd?Spacing | undefined—Padding on block end (bottom).
elevation?"base" | "card" | "raised" | "overlay" | undefined—Elevation levels for visual depth.
rounding?Rounding | undefined—Rounding values for border radius.
alignSelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | undefined—In Flex/Grid layout. Cross-axis alignment within flex/grid container.
justifySelf?"center" | "right" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | "left" | undefined—In Flex/Grid layout. Main-axis alignment within flex/grid container.
order?string | number | undefined—In Flex/Grid layout. Layout order within flex/grid container.
flex?string | number | undefined—In Flex/Grid layout. Flex shorthand for grow, shrink, and basis.
flexGrow?string | number | undefined—In Flex/Grid layout. How much the item will grow relative to siblings.
flexShrink?string | number | undefined—In Flex/Grid layout. How much the item will shrink relative to siblings.
flexBasis?string | undefined—In Flex/Grid layout. Initial main size before growing/shrinking.
gridArea?string | undefined—In Flex/Grid layout. Named grid area for placement.
gridColumnStart?string | undefined—In Flex/Grid layout. Grid column start line.
gridColumnEnd?string | undefined—In Flex/Grid layout. Grid column end line.
gridRowStart?string | undefined—In Flex/Grid layout. Grid row start line.
gridRowEnd?string | undefined—In Flex/Grid layout. Grid row end line.
justifyContent?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly" | undefined—The distribution of space around children along the main axis in flex or inline axis in grid
alignContent?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly" | "baseline" | undefined—The distribution of space around children along the cross axis in flex or block axis in grid
justifyItems?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "legacy" | undefined—Defines the default justify-self for all children in a grid container.
alignItems?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "baseline" | undefined—Sets the align-self property for each child.
gap?Spacing | Spacing[] | undefined—The gap between children.
columnGap?Spacing | undefined—The gap between columns.
rowGap?Spacing | undefined—The gap between rows.
inputMode?"search" | "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | undefined—Hints at the type of data that might be entered by the user while editing the element or its contents
is?string | undefined—Specify that a standard HTML element should behave like a defined custom built-in element
Examples
Basic
You give the chart a data array (id, name, value) and a label in the middle—this is the everyday setup when you want several categories on one ring and a headline number or title in the hole.
import { DonutChart, type DonutChartProps } from '@godaddy/antares';const data = [ { id: '1', name: 'Category A', value: 35 }, { id: '2', name: 'Category B', value: 25 }, { id: '3', name: 'Category C', value: 18 }, { id: '4', name: 'Category D', value: 12 }, { id: '5', name: 'Category E', value: 10 }];export function BasicExample(props: Partial<DonutChartProps>) { return <DonutChart data={data} label="100%" aria-label="Donut chart with five categories" {...props} />;}Single slice
When there is only one slice, the ring is full. Add subLabel if you want a smaller second line under the main center text.
import { DonutChart } from '@godaddy/antares';export function SingleSliceExample() { return ( <DonutChart data={[{ id: 'only', name: 'Total', value: 100 }]} label="$1,000" subLabel="Sub label" aria-label="Donut chart with a single full ring" /> );}Legend placement
Switch legend to right to sit the legend beside the donut, or bottom to stack it underneath. legendLabel is there when you want a title above the legend items.
import { DonutChart, Flex } from '@godaddy/antares';const data = [ { id: '1', name: 'Product A', value: 40 }, { id: '2', name: 'Product B', value: 30 }, { id: '3', name: 'Product C', value: 20 }, { id: '4', name: 'Product D', value: 10 }];export function LegendLayoutExample() { return ( <Flex direction="column" gap="xl"> <DonutChart data={data} label="100%" legend="right" legendLabel="Legend title" aria-label="Donut with legend to the right" /> <DonutChart data={data} label="100%" legend="bottom" legendLabel="Legend title" aria-label="Donut with legend below" /> </Flex> );}Small slices
Very thin slices can be noisy to hover. Anything at or below smallSliceThreshold (default 0.05 of the total) is treated as “small,” and if those slices sit next to each other on the ring, one hover opens a single tooltip that lists the whole group.
import { DonutChart } from '@godaddy/antares';/** Two large slices with two separate clusters of small slices — hover a small slice to see only that adjacent group (A–C or E–G) in the tooltip. */const data = [ { id: 'main', name: 'Primary', value: 88 }, { id: 'a', name: 'Slice A', value: 3 }, { id: 'b', name: 'Slice B', value: 3 }, { id: 'c', name: 'Slice C', value: 3 }, { id: 'd', name: 'Slice D', value: 90 }, { id: 'e', name: 'Slice E', value: 5 }, { id: 'f', name: 'Slice F', value: 4 }, { id: 'g', name: 'Slice G', value: 3 }];export function SmallSlicesExample() { return <DonutChart data={data} label="88%" aria-label="Donut with small slices for combined tooltip" />;}Format value
Use formatValue when the raw numbers in the tooltip should read like money, counts with separators, or whatever your product expects. The percentage of the total still formats on its own; your function only shapes the value column.
import { DonutChart, type DonutChartProps } from '@godaddy/antares';const data = [ { id: '1', name: 'Sales', value: 42 }, { id: '2', name: 'Services', value: 35 }, { id: '3', name: 'Support', value: 23 }];export function FormatValueExample(props: Partial<DonutChartProps>) { return ( <DonutChart data={data} label="$100.00" formatValue={function format(v: number) { return `$${v}.00`; }} aria-label="Donut with formatted tooltip values for multiple revenue categories" {...props} /> );}