# Pie Chart

Pie and donut charts for shares of a whole: pies, donuts, half and nested rings, rose and polar bars, labelled and exploded pies.

- Category: Charts
- Page: https://wunderui.com/components/pie-chart
- Tier: Core and Pro

## Install

Pie Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { PieChart, PieChartProps, PieChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { PieChart } from "@wunderui/react/charts"

const data = [
  { name: "Direct", value: 42 },
  { name: "Referral", value: 26 },
  { name: "Social", value: 18 },
  { name: "Other", value: 14 },
]

export function TrafficSources() {
  return <PieChart data={data} index="name" label="Traffic sources" />
}
```

Expected result: You should see a pie of four slices. Hovering a slice shows its name, value and share.

## When to use

### Use Pie Chart for

- The shares of one whole at one moment, with five slices or fewer
- A donut with the total or the hovered value in the centre
- Goals as concentric rings, or values around a circle (rose, polar bar)

### Use something else

- [Bar Chart](https://wunderui.com/components/bar-chart) for comparing values, or more than five categories
- [Stacked Chart](https://wunderui.com/components/stacked-chart) for shares of a whole over time
- [Radial Chart](https://wunderui.com/components/radial-chart) for progress against a goal
- [Treemap](https://wunderui.com/components/treemap) for parts of a hierarchy

## Keyboard

The plot is focusable: Arrow keys step through the slices in data order and the live region reads name, value and share.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | Moves to the next or previous slice. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one). |
| `Home` or `End` | Jumps to the first or last slice. |
| `Escape` | Clears the active point. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

What the chart does on its own and what the page decides.

- **Slices:** Each data row is a slice. Name the field for the slice name and the field for the number, and set a colour per row if you like.
- **Hit test:** Only the drawn wedge reacts to hover. The hovered slice keeps its strength and the others dim.
- **Centre:** A donut shows the total, or the value of the hovered slice, with a label under it. The number counts up as the chart enters and its size follows the hole. You can set the number or pass your own content.
- **Small shares:** Ring variants keep a minimum arc length, so a small share stays visible.
- **Labels:** The labelled pie writes each slice's name and share on a leader line. When two labels would touch, only the hovered or focused slice keeps its label.
- **Tooltip:** The tooltip takes its form from the chart's own width, like Area, Line and Bar: under 360 px it docks over the top of the chart at its full width, under 560 px it is the compact card, above that the standard card that follows the pointer.
- **Loading, empty and error:** The chart keeps its size while loading, empty or failed, so the card never changes height. Add a retry handler to show a Try again button on error.
- **Legend:** In a ChartCard, each series badge is a button that switches its series off, but the last visible series stays on. A legend of roles can be made static.
- **Data table:** The chart renders its data as a table for screen readers, in the same order as the plot.
- **Size:** The chart fills the width of its container and you set the plot height. Text never scales, so labels keep their size at every width.

## Motion

The enter sequence and the hover follow the motion tokens of the library.

- **Sweep:** Wedges sweep in clockwise and rings draw along their arc when the chart first comes into view, after loading and when new data arrives, while the centre number counts up. Nothing turns or pops. The animation can be turned off.
- **Hover:** The other slices dim and the centre counts to the hovered value.
- **Reduced motion:** With reduced motion on, the chart appears at once without the enter sequence. The tooltip and every state still work.

## Anatomy

- `PieChart`: The chart itself. Pass the data, the field names for slice name and value, and optionally colours, ring width and centre content.
- `Plot`: The focusable region: Arrow keys step through the slices in data order and the live region reads name, value and share. Only the drawn wedge reacts to hover.
- `Marks`: Wedges that sweep in clockwise on first view (their end angles grow) and rings that draw along their arc. While a slice is hovered the others dim; ring variants keep a minimum arc so small shares stay visible. On the nested pie the inner ring hovers and reads like the outer slices.
- `Centre`: The total, or the value of the hovered slice, with a label under it. It counts up from zero as the chart enters and its size follows the hole of the donut, so a small card gets a smaller number. Pass your own content to replace it.
- `Slice labels`: The labelled pie writes each slice's name and share on a leader line. When two labels would touch, only the hovered or focused slice keeps its label.
- `Tooltip`: The slice name with its value and its percent share of the total, anchored to the slice.
- `Loading, empty and error`: A circle or ring skeleton with a shimmer, then the empty and error messages. A pie with all values missing counts as empty.
- `Data table and live region`: A table of every slice and value for screen readers. Slices switched off in the legend are marked as hidden.

## Best practices

### When to use

- Use a pie for three to five shares of one whole, when the point is which part is largest. Use a bar chart for exact comparisons or many categories.

### Do

- Sort slices from largest to smallest and keep to five. Group the rest into one Other slice, since thin wedges are hard to compare by angle.
- Prefer a donut with the total in the centre for a headline number, and add a label such as visits or this week to give it a unit.
- Make names readable without colour: use slice labels, a legend or the tooltip. Neighbouring slices in similar hues are hard to tell apart.

### Don't

- Don't use the rose or polar bar for exact values. Radius is read less accurately than length, so they show a pattern, not precision.
- Don't pass negative values or parts of different wholes. Negatives draw as zero, and unrelated numbers imply a total that does not exist.

## API reference

### PieChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per slice / ring / axis. |
| index* | string |  | Field holding the label. |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  |  |
| animationKey | string \| number |  |  |
| center | React.ReactNode |  | Custom centre content (HTML) instead of the built-in value and label; `null` shows nothing. |
| centerFormatter | (value: number) => string |  | Formats the centre number while it shows the total or centerValue, e.g. visits while the slices are percentages. A hovered slice keeps valueFormatter. |
| centerLabel | string |  | Small text under the centre value ("visits", "this week"). |
| centerValue | number |  | Centre value; defaults to the total (or the hovered slice's value). |
| className | string |  | Extra classes for the root element of the chart. |
| colors | readonly ChartColor[] |  | Colours per row, in order (palette names or token expressions). |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| description | string |  |  |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| explodeIndex | number | 0 | `exploded-pie`: the slice pulled out (default 0). |
| height | number |  | Height of the plot frame in px. Default 280 (Figma small card plot). |
| hiddenSeries | readonly string[] |  | Labels of rows switched off in the legend: drawn faded. |
| innerRadius | number |  | Inner radius as a share of the radius (0…0.95), overriding the variant's ring width. |
| label | string |  | Accessible name, e.g. the card title. |
| max | number | 100 | `multi-ring-donut`: the value of a full ring (default 100). |
| nested | readonly ChartDatum[] |  | `nested-pie`: the inner pie's rows (same `index` / `value` fields). They take part in hover, keyboard, tooltip and table. |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| palette | "series" \| "indigo" | "series" | indigo colours the slices in the indigo tonal scale: 600 for the largest slice, then lighter steps for the smaller ones, with a card-coloured gap between neighbours. The light tones leave their values to the legend and the tooltip. colors still wins. |
| pattern | ChartPattern \| ChartPattern[] |  | One pattern form from the shared pattern library (`diagonal-lines`, `polka-dots`, `crosshatch` …) for every slice, drawn in its colour on a tint of it, for print and colour-blind reading. A list keeps its first entry; a mark under 20 px on its shorter side stays solid. `patterns` (one per slice, the pattern donut) wins when both are set. |
| patterns | (ChartPattern \| null)[] |  | A fill pattern per slice (null = solid), in the slice colour on a tint of it, e.g. solid, stripes and dots in one indigo donut. A slice too small for a few tiles of its pattern stays solid. Several forms in one chart are an exception to the one-pattern rule, for a donut that tells parts apart without hue. |
| rounded | boolean | false | Rounded slice corners from the bar radius tokens (4 px, up to 8 px on thick rings) with an even 2.5 px gap between the slices. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| tooltip | boolean |  |  |
| value | string |  | Field holding the value. Default "value". |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "pie" \| "donut" \| "donut-center-label" \| "half-donut" \| "pad-angle-donut" \| "nested-pie" \| "multi-ring-donut" \| "nightingale-rose" \| "labelled-pie" \| "polar-bar" \| "exploded-pie" \| "rounded-arc-donut" \| "thin-ring-donut" \| "track-ring-donut" \| "rounded-half-donut" | "donut" | Figma variant. Default `donut`. |
| width | number |  |  |

## Examples

### States

### Indigo tones and pattern donut

### Centre text

### Patterns

## In context

### Traffic Sources

Sessions by channel with the channel table.

### Portfolio Allocation

Target allocation with KPI cards and holdings.

### Spend by Category

Monthly spending by category next to the latest transactions.

## For AI agents

`get_component("pie-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
