Charts
PieChart
Parts of one whole.
Usage
When to reach for it
Ships from@misoto22/design/charts
import { PieChart } from '@misoto22/design/charts'Notes
Parts of one whole.
Worth saying plainly: a pie answers "roughly what share" and nothing more precise. Comparing two adjacent wedges by eye is unreliable past about five of them, and comparing a wedge across two pies is worse. When the reader needs to rank or compare, a <BarChart> answers the same question better.
Anatomy
| Element | Description |
|---|---|
| Figure framerequired | ChartFigure’s <figure>, with an empty state at zero rows. There are no axes here, so without one a pie at zero rows was a name over a blank box with the hidden table returning null — the picture and its text equivalent silent together. empty={false} restores that, for a chart whose emptiness is the reading. |
| Wedgesrequired | <PieChart.Pie>. Each sector is painted from a diagonal gradient keyed on the row’s nameKey value, so config keys must match those values exactly — a row whose name is absent from config points at a gradient that was never defined and comes out unpainted. |
| Legend | <PieChart.Legend>, under the pie and centred by default. A pie has no category axis naming its sectors, so this is where the names live. |
| Wedge labels | <PieChart.Label>, a LabelList reversed out in --chart-surface. Its dataKey defaults to the pie’s VALUE key, so composing it prints the numbers. |
| Tooltip | <PieChart.Tooltip>, with the heading suppressed: the wedge’s own name is the row label, so a heading would print it twice. |
Best practices
Do
- Keep it under about five wedges. Past that the reader is ranking angles, which is the comparison a pie is worst at — a BarChart puts the same shares on a length scale and the ranking falls out of the picture for free.
- Compose <PieChart.Label> whenever the exact share matters. It defaults to the value key, and a printed number removes the angle estimate entirely, which is this form’s only real weakness and its cheapest fix.
- Give it an innerRadius. A donut is read by arc LENGTH rather than by wedge area, which the eye does better, and the hole is somewhere to put the total.
Don’t
- A negative value has no wedge. Parts of one whole cannot include a negative part, so a breakdown carrying a refund or churn against expansion is a WaterfallChart, which is built for signed contributions.
- Two pies side by side is not a comparison. Reading a wedge across two circles is harder than reading two wedges inside one, and the reader will try anyway — put the two periods in one grouped BarChart.
- Pass a POSITIVE paddingAngle if the chart has to survive forced colours. There is one fill variant here, so all eight --series-* tokens collapse to CanvasText and every wedge is the same solid shape; what separates them is geometry, and a gap of a degree or two is it. The stroke is not the mechanism — it is drawn only when paddingAngle is NEGATIVE, where the wedges overlap and the surface-coloured stroke re-separates them into stacked cards. 0 is the one value with neither, and a default pie in forced colours is one uniform disc with the legend and the labels carrying the whole reading.
Examples
default
The default composition — wedges, a hover panel and a key. A pie is read by angle, the least precise encoding on offer, so it answers roughly what share and nothing more precise: ranking 275 against 200 by eye is unreliable, and past about five wedges, which is exactly this many, a BarChart answers the same question better. The legend is not decoration here, since a pie has no category axis and nothing else names the sectors; the figure also ships a hidden table of the same rows, which is where the exact numbers live.
| browser | Value |
|---|---|
| chrome | 275 |
| safari | 200 |
| firefox | 187 |
| edge | 173 |
| other | 90 |
shape
Four shapes out of three props — innerRadius, paddingAngle and cornerRadius — over one set of four values. Raising innerRadius above zero makes it a donut, which is the easier of the two to read: the hole takes away the area a reader would otherwise try to judge and leaves the arc. The last option sets a NEGATIVE paddingAngle so the wedges overlap, and the surface-coloured stroke each sector then carries is what re-separates them into stacked cards — a look rather than a reading, since all four shapes draw the same four numbers.
| browser | Value |
|---|---|
| chrome | 275 |
| safari | 200 |
| firefox | 187 |
| edge | 173 |
labels and emphasis
Two answers to the same weakness, side by side. On the left, PieChart.Label prints the value on each wedge: a pie's whole weakness is that an angle is hard to read, and a printed number removes the guess entirely. On the right the question is not the ranking but one wedge — glowingSectors haloes Chrome, and isClickable on both the pie and the legend lets a click drop every other sector to 15 percent opacity so the chosen one stands alone. Reach for the labels when the numbers matter, and for the glow when only one of them does.
| browser | Value |
|---|---|
| chrome | 275 |
| safari | 200 |
| firefox | 187 |
| edge | 173 |
| browser | Value |
|---|---|
| chrome | 275 |
| safari | 200 |
| firefox | 187 |
| edge | 173 |
loading
The skeleton. isLoading swaps the marks for five equal wedges and keeps the figure's measured height, so the page does not jump when the real data lands. They pulse on a stagger, which is what sends the wave round the pie rather than blinking the whole of it at once; under prefers-reduced-motion they hold at a flat mid-opacity instead. Compose the parts you would compose with data — innerRadius is read in this state too, so the loading donut is the same shape as the one that replaces it.
Types
export type PieVariant = 'gradient'Accessibility
- title is required; the rows are also rendered as a visually hidden table.
- The legend sits under the pie by default, because a pie has no category axis naming its sectors.
- Compose a Label to print the numbers on the wedges: a pie’s weakness is that an angle is hard to read, and a printed number removes the guess.
- One fill variant, deliberately. A wedge is small and awkwardly shaped, and a texture inside one reads as noise.