PieChart
Pie or donut chart with hover segments and optional legend.
Category: chart · WCAG 2.1-AA · chart, pie, donut, data-viz
Variants
- pie
- donut
Props
| Prop | Type | Default | Description |
|---|---|---|---|
data | PieChartDatum[] | — | Array of { id, label, value, color? } datums. Optional per-datum `color` (any CSS color) overrides the positional palette for that slice. |
title | string | — | Title text for the component. |
description | string | — | Supporting description text. |
donut | boolean | — | Render as donut chart |
width | number | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
height | number | 300 | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
size | number | — | Square shorthand: sets width === height. Explicit width/height win. |
thickness | number | — | Ring width in px (donut only); defaults to 0.4 × radius. |
innerRadius | number | — | Inner radius in px (donut only); takes precedence over thickness; clamped to [0, outerRadius). |
centerValue | string | — | Center value text rendered in the donut hole (donut only). |
centerLabel | string | — | Center label text rendered below the value (donut only). |
centerSlot | ReactNode | — | Arbitrary content for the donut hole; takes precedence over centerValue/centerLabel. |
emptyLabel | string | — | Visible placeholder text when data is empty. Defaults to the i18n "No data". |
tooltipFormat | (p: ChartPoint) => string | — | Custom tooltip formatter. Defaults to "value (pct%)" in the slice color. |
legend | boolean | — | Whether to show the legend. |
className | string | — | Additional CSS class names merged onto the root element. |
plain | boolean | false | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
labels | boolean | { format?: (v: number) => string; position?: string } | — | Print each value as a label on the mark (collision-aware, decorative/aria-hidden). |
onSelect | (point: ChartPoint) => void | — | Fired when a point is clicked or activated (Enter/Space) — for drill-down. |
Design tokens
--cascivo-chart-1--cascivo-chart-2--cascivo-chart-3--cascivo-chart-4--cascivo-chart-5--cascivo-chart-6--cascivo-chart-7--cascivo-chart-8
When to use
- Showing part-of-whole proportions with five or fewer slices
- A single composition at one point in time
When not to use
- Comparing precise values or many categories — use BarChart
- Showing change over time — use LineChart or AreaChart
Examples
Basic pie chart
import { PieChart } from '@cascivo/charts'
<PieChart data={[{label:'A',value:60},{label:'B',value:40}]} title="Market share" />Donut with center total and custom thickness
import { PieChart } from '@cascivo/charts'
<PieChart
donut
size={220}
thickness={28}
centerValue="142"
centerLabel="Total tasks"
data={[
{ id: 'done', label: 'Done', value: 92, color: 'var(--cascivo-color-success)' },
{ id: 'wip', label: 'In progress', value: 34, color: 'var(--cascivo-color-warning)' },
{ id: 'blocked', label: 'Blocked', value: 16, color: 'var(--cascivo-color-destructive)' },
]}
title="Task status"
/>Percentage tooltip + empty state
import { PieChart } from '@cascivo/charts'
// Default tooltip shows "value (pct%)" in the slice color; pass tooltipFormat to override.
<PieChart data={[{id:'a',label:'A',value:60},{id:'b',label:'B',value:40}]} title="Share" />
// Empty data renders a visible "No data" placeholder (override via emptyLabel).
<PieChart data={[]} title="Share" emptyLabel="Nothing tracked yet" />