# Pie Chart (/docs/charts/components/pie)

Use a pie chart to show a few parts of one total, like hours by team or budget by category. Keep it to a handful of slices; for more, or to compare totals, use a [bar chart](./bar.mdx).

<Example caption="Hover a slice, or focus the chart and press the arrow keys, to see its hours.">
<Basic />

```tsx
"use client";

import { PieChart, type SeriesConfig } from "@kind-ui/charts";

const hours = (value: unknown) => `${value} hours`;

const config = {
  design: { label: "Design", color: "#733bff", formatValue: hours },
  engineering: { label: "Engineering", color: "#2469d4", formatValue: hours },
  operations: { label: "Operations", color: "#b65c16", formatValue: hours },
  research: { label: "Research", color: "#147c68", formatValue: hours },
} satisfies SeriesConfig;

const data = [
  { team: "design", hours: 420, share: "42%" },
  { team: "engineering", hours: 310, share: "31%" },
  { team: "operations", hours: 170, share: "17%" },
  { team: "research", hours: 100, share: "10%" },
];

export default function TeamAllocationChart() {
  return (
    <PieChart
      config={config}
      height={280}
      animate
      interaction={{ kind: "category", eligibleKeys: data.map((row) => row.team) }}
      aria-label="Team allocation, 1,000 hours"
    >
      <PieChart.Series
        data={data}
        dataKey="hours"
        nameKey="team"
        categoryKey="team"
        outerRadius={108}
      >
        <PieChart.Labels dataKey="share" position="inside" fill="white" stroke="none" />
      </PieChart.Series>
      <PieChart.Tooltip itemKey={(entry) => entry.payload.team} />
      <PieChart.Legend />
    </PieChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/pie-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
PieChart
├── PieChart.Series
│   ├── PieChart.Cell
│   └── PieChart.Labels
├── PieChart.Tooltip
├── PieChart.Legend
└── PieChart.Content
```

`PieChart` holds the series config and the accessible name, and draws only the parts you add. `PieChart.Series` draws one sector per row. `PieChart.Labels` writes a row field on each sector, and `PieChart.Cell` paints one sector by hand. `PieChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Categories [#categories]

Each row is a category. Set `categoryKey` on the series to the field holding the category's `config` key: the sector takes its color from there, and the tooltip and legend use its label. `dataKey` is the value that sizes the sector, and `nameKey` is what the tooltip reads, so point it at the same field. Give `PieChart.Tooltip` an `itemKey` that returns the same key.

List every category in `interaction.eligibleKeys`, including any with a value of `0`, so the legend can reach them.

### Donut and Rounded Sectors [#donut-and-rounded-sectors]

Set `innerRadius` for a donut. `cornerRadius` rounds the sector ends, and `paddingAngle` adds a gap in degrees between sectors. Keep the total padding well under the full circle; very thin sectors lose their rounding.

<Example caption="Press a team in the legend to hide its slice. The other slices stay where they are.">
<Donut />

```tsx
"use client";

import { PieChart, type SeriesConfig } from "@kind-ui/charts";

const hours = (value: unknown) => `${value} hours`;

const config = {
  design: { label: "Design", color: "#733bff", formatValue: hours },
  engineering: { label: "Engineering", color: "#2469d4", formatValue: hours },
  operations: { label: "Operations", color: "#b65c16", formatValue: hours },
  research: { label: "Research", color: "#147c68", formatValue: hours },
} satisfies SeriesConfig;

const data = [
  { team: "design", hours: 420 },
  { team: "engineering", hours: 310 },
  { team: "operations", hours: 170 },
  { team: "research", hours: 100 },
];

export default function TeamDonutChart() {
  return (
    <PieChart
      config={config}
      height={280}
      defaultVisibleSeries={Object.keys(config)}
      interaction={{
        kind: "category",
        mode: "visibility",
        eligibleKeys: data.map((row) => row.team),
      }}
      aria-label="Team allocation, 1,000 hours"
    >
      <PieChart.Series
        data={data}
        dataKey="hours"
        nameKey="team"
        categoryKey="team"
        innerRadius={58}
        outerRadius={108}
        cornerRadius={8}
        paddingAngle={2}
      />
      <PieChart.Tooltip itemKey={(entry) => entry.payload.team} />
      <PieChart.Legend />
    </PieChart>
  );
}
```
</Example>

### Legend and Keyboard [#legend-and-keyboard]

By default, pressing a legend item highlights its slice and dims the others, and screen readers hear "Highlighted Design." Press it again, or press Escape, to clear it. Pressing a slice does the same.

With `interaction={{ kind: "category", mode: "visibility", ... }}` and `defaultVisibleSeries`, the legend hides and shows slices instead, and screen readers hear "Hidden Design." A hidden slice keeps its angle, so the others don't move, and the last visible slice can't be hidden. Pass `visibleSeries` and `onVisibleSeriesChange` to control it yourself. See [Legend](../building-blocks/legend.mdx).

Focus the chart and press the arrow keys to move between slices, which shows the tooltip, and Escape to dismiss it.

### Open Tooltip [#open-tooltip]

Set `defaultPinnedCategory` to open one category's tooltip on mount, like the largest share. It follows that category if the rows reorder, and closes for good as soon as the reader hovers, focuses or presses a key:

```tsx
<PieChart defaultPinnedCategory="design" {...props}>
```

### Materials [#materials]

Set `material="clay"` or `"glow"` on the series for a finish on every sector, or `glowCategories={["design"]}` to make only some of them glow. See [Materials](../guides/materials.mdx).

### Motion [#motion]

With `animate`, the sectors sweep in when the chart mounts. Set `animationDirection="anticlockwise"` to reverse the sweep, and pass `animate={{ revealDurationMs: 800 }}` to change its length. When the reader prefers reduced motion, the sectors appear without sweeping in. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder pie that sweeps around the circle, or holds still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default):

```tsx
<PieChart loading={isPending} loadingLabel="Loading allocation" {...props}>
```

## API Reference [#api-reference]

### PieChart [#piechart]

### PieChartOptions

| Prop                     | Type                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show, when you control visibility.                                                                                                                                                 |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show first, when the chart controls visibility.                                                                                                                                    |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                              | Called with the next visible series keys when the legend hides or shows one.                                                                                                                          |
| `defaultPinnedCategory?` | `string \| undefined`                                                                                                                                                                                                                                | The category whose tooltip is open on mount, until the reader hovers, focuses or presses a key. Needs one `PieChart.Series` with `categoryKey` and `data`, and one `PieChart.Tooltip` with `itemKey`. |
| `animate?`               | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                              | Sweeps the sectors in on mount. Pass options to change the duration or easing. Reduced motion skips it. Default: `false`                                                                              |
| `loading?`               | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                                                                                               |
| `loadingLabel?`          | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                                                                            |
| `animationDirection?`    | `"anticlockwise" \| "clockwise"`                                                                                                                                                                                                                     | Which way the entrance sweeps. The sector angles and data order don't change. Default: `"clockwise"`                                                                                                  |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                                                                                              |
| `emphasis?`              | `"auto" \| "none"`                                                                                                                                                                                                                                   | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"`                                                                                                       |
| `interaction?`           | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                                                                                               |
| `aria-label?`            | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                                                                                          |
| `aria-labelledby?`       | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                                                                                                 |
| `legendPosition?`        | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                                                                                                   |
| `frameProps?`            | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                                                                                                |

### PieChart.Series [#piechartseries]

### PieSeriesOptions

| Prop              | Type                                                                 | Description                                                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `categoryKey?`    | `((row: unknown) => string) \| undefined`                            | The row field, or a function of the row, naming each sector's `config` entry. It sets the sector's color and links it to the legend and tooltip. Needs `data` on the series. |
| `material?`       | `"clay" \| "glow" \| "plain"`                                        | A `"clay"` or `"glow"` finish on the default sectors. Custom shapes keep their own paint.                                                                                    |
| `glowCategories?` | `readonly string[] \| undefined`                                     | Category keys that glow, whatever `material` is. Needs `categoryKey`; unknown keys are ignored.                                                                              |
| `emphasisKey?`    | `((payload: unknown) => string \| number \| undefined) \| undefined` | The sector's identity for hover emphasis. Defaults to its `nameKey` value.                                                                                                   |

<Caption>
`PieChart` and `PieChart.Series` also take every prop of Recharts' [PieChart](https://recharts.github.io/en-US/api/PieChart/) and [Pie](https://recharts.github.io/en-US/api/Pie/), like `height`, `innerRadius` and `paddingAngle`.
</Caption>