PieChart

Donut and pie charts with a center label and a value-and-share legend.

stable

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/APITypeDefaultDescription
datareadonly T[]requiredOne row per slice.
categoryKeystring or number field of TrequiredField naming each slice. Values must be unique.
valueKeynumeric field of TrequiredNonnegative value sized into each slice.
ariaLabelstringrequiredAccessible chart name.
colorKeystring field of TpaletteField holding a slice's CSS color.
variant"donut" | "pie""donut"Donut leaves a hole for the center label.
centerValuestring | number-Donut center headline, such as the total. Ignored for pie.
centerCaptionstring-Caption under centerValue.
size"sm" | "md" | "lg"inherited, otherwise "md"Plot size and legend type (PIE_CHART_LAYOUT).
legend"right" | "bottom" | booleantrue ("right")Legend rows with value and share, beside or under the plot. Rows toggle their slice.
legendMinWidthnumber200Narrowest a right legend gets, in px, before it wraps under the plot.
tooltipbooleantrueHover and keyboard tooltip.
formatValue(value: number) => stringgrouped numberLegend and tooltip values.
formatShare(share: number) => stringwhole percentLegend and tooltip shares; share is 0–1.
formatCategory(value: string | number) => stringStringSlice names.
emptyMessageReactNode"No data to display"Shown when no valid values exist.
Chart host propssee Chart-initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
PieChartLegenditems, 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, PieChartDefinitiontypes-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.

On this page