Component reference
DonutChart
Show proportions with an explorable ring and a central summary.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Loading the interactive example?
Width adapts to the available space
"use client";
import { DonutChart } from "@pimolu/react";
export function DonutChartExample() {
const data = [
{ label: "Completed", value: 62 },
{ label: "In review", value: 24 },
{
label: "Planned",
value: 14
}
];
return (
<DonutChart
aria-label="Fictional DonutChart dataset"
data={data}
centerValue="100"
centerLabel="Total tasks"
/>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Distribution with a total
Pair category names with a clear summary.
Custom palette
Supply explicit colors while keeping named categories.
Compact summary
Use a thinner ring and retain the accessible data alternative.
Named-part customization
Style this chart directly through typed geometry and surface hooks.
Usage
Provide non-negative category values through data. centerValue and centerLabel summarize the dataset; thickness controls the ring.
Use valueFormatter for readable units. These charts do not implement zoom, pan or time-axis aggregation. Demo data is fictional.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluChartDatum
Type source| Name | Type | Default | Description |
|---|---|---|---|
labelRequired | string | — | Category label shown on the axis, in the legend and in the data table. |
valueRequired | number | — | Numeric value of the category. |
color | string | undefined | — | Explicit colour. Falls back to the chart palette and theme tokens. |
labelRequiredstringNo default extracted.
Category label shown on the axis, in the legend and in the data table.
valueRequirednumberNo default extracted.
Numeric value of the category.
colorstring | undefinedNo default extracted.
Explicit colour. Falls back to the chart palette and theme tokens.
PimoluDonutChartProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
classNames | PimoluClassNames<"chart"> | undefined | — | Additive classes for stable named parts, including composed descendants. Parts: area, axis, axisLabel, axisTitle, bar, canvas, centerLabel, centerValue, cursor, donutTrack, empty, grid, legend, legendItem, legendLabel, legendSwatch, legendValue, line, point, root, segment, srOnly, svg, tooltip, tooltipRow, valueLabel. Parts render only when the corresponding component or state is present. |
dataRequired | PimoluChartDatum[] | [] | Segments of the ring. Values are treated as positive weights. |
centerValue | string | undefined | — | Large text in the middle of the ring, for example a total. |
centerLabel | string | undefined | — | Small caption under the centre value. |
thickness | number | undefined | 28 | Ring thickness in viewBox units. Defaults to 28. |
width | number | undefined | — | Initial viewBox width, default 640 (240 for DonutChart). Bar/Line/Area measure their container by default; set responsive=false to retain this viewBox width and the original fluid aspect ratio. |
height | number | undefined | 320 (or 240 for the donut) | viewBox height. Responsive Cartesian charts retain this drawing height. Defaults to 320 (or 240 for the donut). |
showLegend | boolean | undefined | — | Shows the legend below the chart. |
showTooltip | boolean | undefined | true | Enables pointer, touch and arrow-key exploration. Defaults to true. |
interactionLabel | string | undefined | — | Localized instructions for keyboard exploration. |
valueFormatter | ((value: number) => string) | undefined | — | Formats values in the axis, value labels, legend and data table. |
emptyLabel | string | undefined | — | Text announced when there is nothing to draw. |
onChange | ChangeEventHandler<HTMLDivElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
classNamesPimoluClassNames<"chart"> | undefinedNo default extracted.
Additive classes for stable named parts, including composed descendants. Parts: area, axis, axisLabel, axisTitle, bar, canvas, centerLabel, centerValue, cursor, donutTrack, empty, grid, legend, legendItem, legendLabel, legendSwatch, legendValue, line, point, root, segment, srOnly, svg, tooltip, tooltipRow, valueLabel. Parts render only when the corresponding component or state is present.
dataRequiredPimoluChartDatum[]Default: []
Segments of the ring. Values are treated as positive weights.
centerValuestring | undefinedNo default extracted.
Large text in the middle of the ring, for example a total.
centerLabelstring | undefinedNo default extracted.
Small caption under the centre value.
thicknessnumber | undefinedDefault: 28
Ring thickness in viewBox units. Defaults to 28.
widthnumber | undefinedNo default extracted.
Initial viewBox width, default 640 (240 for DonutChart). Bar/Line/Area measure their container by default; set responsive=false to retain this viewBox width and the original fluid aspect ratio.
heightnumber | undefinedDefault: 320 (or 240 for the donut)
viewBox height. Responsive Cartesian charts retain this drawing height. Defaults to 320 (or 240 for the donut).
showLegendboolean | undefinedNo default extracted.
Shows the legend below the chart.
showTooltipboolean | undefinedDefault: true
Enables pointer, touch and arrow-key exploration. Defaults to true.
interactionLabelstring | undefinedNo default extracted.
Localized instructions for keyboard exploration.
valueFormatter((value: number) => string) | undefinedNo default extracted.
Formats values in the axis, value labels, legend and data table.
emptyLabelstring | undefinedNo default extracted.
Text announced when there is nothing to draw.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Give the chart a descriptive aria-label including its units. A hidden data table provides the individual observations.
- One Tab stop enters exploration. Arrow keys move between observations, Home/End jump, and Escape closes the tooltip while keeping focus.