PieChart
Donut and pie charts with a center label and a value-and-share legend.
Quick Preview
Portfolio mix
Usage
import { PieChart } from "@giddaa-housing/ui/pie-chart";
<PieChart
data={[
{ label: "Lekki", value: 42 },
{ label: "Ikoyi", value: 28 },
{ label: "Yaba", value: 18 },
]}
categoryKey="label"
valueKey="value"
centerValue="88"
centerCaption="Listings"
ariaLabel="Listings by neighbourhood"
/>PieChart takes one row per slice. It renders the plot and a legend with each
slice's value and share. Shares are computed from the data. Slices start at
twelve o'clock and run clockwise; focus or hover a slice to dim the others. Click
a legend row to hide its slice: the remaining shares are taken of what is still
shown, and colors stay put. Values must be nonnegative; missing values are omitted
and categories must be unique.
Any number of slices is allowed. The first four take chart-1…chart-4; past
four, fold the long tail into an "Other" slice colored CHART_OTHER_COLOR, or set
each slice's color with colorKey.
Examples
Donut with legend
A donut with a center total and the legend (name · value · share).
Portfolio mix
Legend placement
legend="right" (the default) puts the legend beside the plot, filling the width
the plot leaves. Below legendMinWidth (200px by default) it drops under the
plot. legend="bottom" always stacks: the plot is centered and the legend spans
the full width.
To stack the legend on phones, raise legendMinWidth so it wraps sooner. The
switch follows the chart's own width, not the viewport, so it also stacks in a
narrow card on a wide screen.
<PieChart {...props} legendMinWidth={280} />Share precision
Shares are whole percents by default. Pass formatShare for more precision; it
formats the legend and the tooltip.
<PieChart
{...props}
formatShare={(share) => `${(share * 100).toFixed(2)}%`} // 35.67%
/>Solid pie with an "Other" fold
variant="pie" fills the hole. The long tail is folded into a neutral "Other"
slice through colorKey.
Financing split
Solid pie · long-tail categories folded into “Other”
import { CHART_OTHER_COLOR } from "@giddaa-housing/ui/chart";
<PieChart
data={[
{ label: "Mortgage", value: 46 },
{ label: "Outright", value: 31 },
{ label: "Other", value: 9, color: CHART_OTHER_COLOR },
]}
categoryKey="label"
valueKey="value"
colorKey="color"
variant="pie"
ariaLabel="Financing split by type"
/>Props
| Prop/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | One row per slice. |
categoryKey | string or number field of T | required | Field naming each slice. Values must be unique. |
valueKey | numeric field of T | required | Nonnegative value sized into each slice. |
ariaLabel | string | required | Accessible chart name. |
colorKey | string field of T | palette | Field holding a slice's CSS color. |
variant | "donut" | "pie" | "donut" | Donut leaves a hole for the center label. |
centerValue | string | number | - | Donut center headline, such as the total. Ignored for pie. |
centerCaption | string | - | Caption under centerValue. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Plot size and legend type (PIE_CHART_LAYOUT). |
legend | "right" | "bottom" | boolean | true ("right") | Legend rows with value and share, beside or under the plot. Rows toggle their slice. |
legendMinWidth | number | 200 | Narrowest a right legend gets, in px, before it wraps under the plot. |
tooltip | boolean | true | Hover and keyboard tooltip. |
formatValue | (value: number) => string | grouped number | Legend and tooltip values. |
formatShare | (share: number) => string | whole percent | Legend and tooltip shares; share is 0–1. |
formatCategory | (value: string | number) => string | String | Slice names. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid values exist. |
| Chart host props | see Chart | - | initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
PieChartLegend | items, size?, hidden?, onToggle? + ul props | - | The legend on its own; items are { key?, label, color, value, percentage }. With onToggle, rows are toggle buttons. |
formatPieShare | (share: number) => string | - | The default share format. |
createPieChartDefinition(options) | function | - | Same options without the HTML legend; returns an extensible TanStack definition. |
PieChartOptions, PieChartSlice, PieChartDatum, PieChartDefinition | types | - | Exported for typed builders. |
Accessibility
- Provide a meaningful
ariaLabel; slices are keyboard-focusable with arrow keys. - Keep the legend on: it repeats each value and share as text, so color is never the only cue.
- Legend rows are buttons with
aria-pressed; the last visible slice cannot be hidden. - Prefer a bar chart when slices are close in size or there are more than five.