/// Charts

PieChart

A monochrome-plus-signal pie chart with sharp sectors and a custom legend; DonutChart is the same wrapper with a ring cutout.

import { PieChart, DonutChart } from "@protocore/pds";

View as Markdown

Import path

PieChart and DonutChart ship from the `@protocore/pds/charts` subpath so recharts stays out of the core bundle. recharts (>=3) is an optional peer; install it in apps that render charts.

import { PieChart, DonutChart } from "@protocore/pds/charts";
import { ChartContainer } from "@protocore/pds";

Pie

Pass data and (optionally) dataKey/nameKey. Sectors are sharp (corner radius 0, matching the system's control geometry), hairline-separated in the surface colour, and coloured from the --pds-chart-N ramp — grey by default, with a signal hue reserved for the slice that carries meaning. The custom legend renders beneath the plot.

Requests by status class · 24h

Donut

DonutChart is the same wrapper with a non-zero innerRadius — a ring. Use the negative space in the middle for a headline number (a RadialProgress or a plain figure) so the part-to-whole reading and the total sit together.

Active tenants by plan

When to use it

Use a PieChart or DonutChart to show a handful of parts making up a whole where the categories are few (three to five) and the shares are visibly different — status-class mix, plan distribution, spend by category. Beyond five slices, or when precise comparison matters, a PercentageBarChart or BarChart reads more honestly.

Spend a signal hue on at most one slice; let the rest stay monochrome (see the doctrine on ChartContainer).

Usage

Keep it to three to five slices with clearly different shares.
Let slices stay grey and spend a signal hue on the one that matters.
Use DonutChart when you want a headline total in the middle.
Wrap it in a ChartContainer so it inherits the `--pds-chart-*` ramp.

Don't

Don't use a pie for many near-equal slices — that's a bar or percentage bar.
Don't round the sectors or add shadows; sharp geometry is the house style.
Don't import it from `@protocore/pds`; it lives on the `/charts` subpath.
Don't rely on colour alone — the legend labels every slice.

Accessibility

recharts renders the plot as SVG; provide surrounding context (a ChartContainer `label`, caption, or data table) since individual sectors are not labelled.
The custom legend labels every slice, so the chart stays readable in grayscale and for colour-vision deficiencies.
The default tooltip surfaces per-slice values on hover and keyboard focus via recharts.

`PieChart` props

Prop	Type	Default	Description
`data` *	`ReadonlyArray<Record<string, string \| number \| null \| undefined>>`	—	One datum per slice; each keyed by `nameKey` (label) and `dataKey` (value).
`dataKey`	`string`	`"value"`	Datum key for each slice's numeric value.
`nameKey`	`string`	`"name"`	Datum key for each slice's label.
`colors`	`string[]`	—	Per-slice colour overrides, in data order. Defaults to the `--pds-chart-N` ramp.
`innerRadius`	`number \| string`	`0 (PieChart) · "58%" (DonutChart)`	Inner radius (donut hole) — px or a percentage string.
`outerRadius`	`number \| string`	`"80%"`	Outer radius — px or a percentage string.
`legend`	`boolean`	`true`	Render the custom swatch/label legend below the plot.
`height`	`number`	`240`	Chart height in px (plot + legend).
`...rest`	`Omit<RechartsPieChartProps, 'data' \| 'children' \| 'width' \| 'height' \| 'ref'>`	—	Remaining props spread onto the underlying recharts `<PieChart>`.

`DonutChart` props

Prop	Type	Default	Description
`data` *	`ReadonlyArray<Record<string, string \| number \| null \| undefined>>`	—	One datum per slice; each keyed by `nameKey` (label) and `dataKey` (value).
`dataKey`	`string`	`"value"`	Datum key for each slice's numeric value.
`nameKey`	`string`	`"name"`	Datum key for each slice's label.
`colors`	`string[]`	—	Per-slice colour overrides, in data order. Defaults to the `--pds-chart-N` ramp.
`innerRadius`	`number \| string`	`0 (PieChart) · "58%" (DonutChart)`	Inner radius (donut hole) — px or a percentage string.
`outerRadius`	`number \| string`	`"80%"`	Outer radius — px or a percentage string.
`legend`	`boolean`	`true`	Render the custom swatch/label legend below the plot.
`height`	`number`	`240`	Chart height in px (plot + legend).
`...rest`	`Omit<RechartsPieChartProps, 'data' \| 'children' \| 'width' \| 'height' \| 'ref'>`	—	Remaining props spread onto the underlying recharts `<PieChart>`.