# Radial Chart (/docs/charts/components/radial)

Use a radial chart to show how far a few measures are toward a goal, like project stages or storage used. Each bar is an arc, and a full circle (or half, for a gauge) is the goal.

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

```tsx
"use client";

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

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

const config = {
  design: { label: "Design", color: "#733bff", formatValue: percent },
  build: { label: "Build", color: "#008b83", formatValue: percent },
  review: { label: "Review", color: "#b85c13", formatValue: percent },
} satisfies SeriesConfig;

const data = [
  { stage: "design", label: "Design 92%", progress: 92 },
  { stage: "build", label: "Build 76%", progress: 76 },
  { stage: "review", label: "Review 58%", progress: 58 },
];

export default function ProjectProgressChart() {
  return (
    <RadialBarChart
      config={config}
      data={data}
      categoryKey="stage"
      height={280}
      animate
      startAngle={90}
      endAngle={-270}
      innerRadius="18%"
      outerRadius="94%"
      barCategoryGap="4%"
      aria-label="Project completion by stage"
    >
      <RadialBarChart.AngleAxis type="number" domain={[0, 100]} tick={false} />
      <RadialBarChart.RadiusAxis type="category" dataKey="stage" tick={false} axisLine={false} />
      <RadialBarChart.Series dataKey="progress" background cornerRadius={5}>
        <RadialBarChart.Labels dataKey="label" fill="white" content={<RadialBarChart.Label />} />
      </RadialBarChart.Series>
      <RadialBarChart.Tooltip
        itemKey={(entry) => entry.payload.stage}
        labelFormatter={() => "Completion"}
      />
    </RadialBarChart>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
RadialBarChart
├── RadialBarChart.Grid
├── RadialBarChart.AngleAxis
├── RadialBarChart.RadiusAxis
├── RadialBarChart.Series
│   ├── RadialBarChart.Cell
│   └── RadialBarChart.Labels
│       └── RadialBarChart.Label
├── RadialBarChart.Tooltip
├── RadialBarChart.Legend
└── RadialBarChart.Content
```

`RadialBarChart` holds the data, the series config and the accessible name, and draws only the parts you add. `RadialBarChart.AngleAxis` sets the scale around the circle, and `RadialBarChart.RadiusAxis` gives each row its own ring. `RadialBarChart.Series` draws the arcs. `RadialBarChart.Labels` writes a row field on each arc, and `RadialBarChart.Label` fits that text along it. `RadialBarChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Scale and Rings [#scale-and-rings]

Give `RadialBarChart.AngleAxis` a fixed `domain`, like `[0, 100]`, so a full circle always means the same thing, and `tick={false}` to hide its numbers. Each row gets its own ring when `RadialBarChart.RadiusAxis` has `type="category"` and the row field as its `dataKey`. `innerRadius` and `outerRadius` set where the rings sit, and `barCategoryGap` the space between them.

Set `categoryKey` on the chart to the field holding each row's `config` key, so each ring takes its own color and the tooltip its label. Pass `background` to the series for a pale track behind each arc, and `cornerRadius` to round the ends. Set the `--kind-ui-radial-track` CSS variable to change the track color, like for a dark theme.

`startAngle` and `endAngle` set where the circle starts and which way it runs. The example starts at the top (`90`) and runs clockwise to `-270`.

### Labels [#labels]

Put `RadialBarChart.Label` in `RadialBarChart.Labels` as its `content` to write text along each arc. It shrinks the text to fit the ring, down to `minFontSize`, and hides it if it still doesn't fit. Set `show={false}` to hide it; the tooltip still has the value.

### Gauge [#gauge]

For a half-circle gauge, set `startAngle={180}` and `endAngle={0}`, and move the center down with `cy` so the arc fills the space:

<Example caption="Hover the arc to see how much storage is used.">
<Gauge />

```tsx
"use client";

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

const config = {
  used: { label: "Used", color: "#008b83", formatValue: (value: unknown) => `${value} of 100 GB` },
} satisfies SeriesConfig;

const data = [{ disk: "Storage", used: 72 }];

export default function StorageGaugeChart() {
  return (
    <RadialBarChart
      config={config}
      data={data}
      height={280}
      animate
      startAngle={180}
      endAngle={0}
      cy="78%"
      innerRadius="100%"
      outerRadius="140%"
      aria-label="Storage used, 72 of 100 GB"
    >
      <RadialBarChart.AngleAxis type="number" domain={[0, 100]} tick={false} />
      <RadialBarChart.RadiusAxis type="category" dataKey="disk" tick={false} axisLine={false} />
      <RadialBarChart.Series dataKey="used" background cornerRadius={6} />
      <RadialBarChart.Tooltip />
    </RadialBarChart>
  );
}
```
</Example>

### Stacked Arcs [#stacked-arcs]

Series with the same `stackId` share one ring, end to end, like committed and reserved hours out of a total:

```tsx
<RadialBarChart.Series dataKey="committed" stackId="capacity" background />
<RadialBarChart.Series dataKey="reserved" stackId="capacity" />
```

### Activity Rings [#activity-rings]

`ActivityRings` draws progress rings from a list of goals, without axes to set up. Each ring has a `key` in `config`, a `value`, and the `domain` its full circle stands for, so each one can have its own goal. Rings run from the inside out in list order.

<Example caption="Press a ring in the legend to highlight it. Hover a ring to see its value.">
<Activity />

```tsx
"use client";

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

const config = {
  move: { label: "Move", color: "#e02266", formatValue: (value: unknown) => `${value} kcal` },
  exercise: {
    label: "Exercise",
    color: "#327448",
    formatValue: (value: unknown) => `${value} min`,
  },
  stand: { label: "Stand", color: "#2469d4", formatValue: (value: unknown) => `${value} hours` },
} satisfies SeriesConfig;

const rings = [
  { key: "move", value: 350, domain: [0, 500] as const },
  { key: "exercise", value: 30, domain: [0, 60] as const },
  { key: "stand", value: 9, domain: [0, 12] as const },
];

export default function DailyActivityChart() {
  return (
    <ActivityRings rings={rings} config={config} animate aria-label="Daily activity">
      <ActivityRings.Series />
      <ActivityRings.Tooltip />
      <ActivityRings.Legend />
    </ActivityRings>
  );
}
```
</Example>

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/activity-rings
```

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

A value past its goal fills the ring and stops; the tooltip still shows the real value, formatted by `config`. Screen readers hear every ring's label and value when the chart gets focus. `ActivityRings.Series` draws the tracks and arcs, and takes `RadialBarChart.Series` props like `cornerRadius`. Add `ActivityRings.Labels` inside it to write each ring's label along its arc.

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

Pressing a legend item highlights its ring and dims the others, and screen readers hear "Highlighted Move." Press it again, or press Escape, to clear it. To hide and show rings from the legend instead, see [Legend](../building-blocks/legend.mdx).

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

### Materials [#materials]

Set `material="clay"` or `"glow"` on a series for a finish. See [Materials](../guides/materials.mdx).

### Motion [#motion]

With `animate`, the arcs sweep in when the chart mounts. Set `animationDirection="anticlockwise"` to reverse the sweep, and pass `animate={{ revealDurationMs: 1200 }}` to change its length. When the reader prefers reduced motion, the arcs 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 placeholder rings that sweep around the circle, or hold still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default). `ActivityRings` takes the same props.

## API Reference [#api-reference]

### RadialBarChart [#radialbarchart]

### RadialBarChartOptions

| 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.                                                           |
| `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.                                                 |
| `categoryKey?`           | `((row: unknown) => string) \| undefined`                                                                                                                                                                                                            | The row field, or a function of the row, naming each bar's `config` entry, so each bar takes its own color.                            |
| `animate?`               | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                              | Sweeps the bars in along their arcs 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. `startAngle` and `endAngle` don't change. Default: `"clockwise"`                                        |

### RadialBarChart.Series [#radialbarchartseries]

### RadialBarSeriesOptions

| Prop         | Type                          | Description                                                                                                            |
| ------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `seriesKey?` | `string \| undefined`         | The series' `config` key. Defaults to `dataKey` when it's a string; required for a function `dataKey` with visibility. |
| `material?`  | `"clay" \| "glow" \| "plain"` | A `"clay"` or `"glow"` finish on the default marks. Custom shapes keep their own paint.                                |

### RadialBarChart.Label [#radialbarchartlabel]

### RadialBarLabelOptions

| Prop           | Type                   | Description                                                                               |
| -------------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| `show?`        | `boolean \| undefined` | Shows the label. Hiding it leaves the tooltip as it is. Default: `true`                   |
| `fontSize?`    | `number \| undefined`  | Text size in pixels, shrunk to fit the ring, but never below `minFontSize`. Default: `11` |
| `minFontSize?` | `number \| undefined`  | The smallest size to shrink to. Text that still doesn't fit is hidden. Default: `9`       |
| `padding?`     | `number \| undefined`  | Space in pixels at the arc's ends and edges. Default: `2`                                 |

### ActivityRings [#activityrings]

### ActivityRingsOptions

| 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.                                                           |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                               |
| `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.                                                 |
| `animate?`               | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                  | Sweeps the bars in along their arcs 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. `startAngle` and `endAngle` don't change. Default: `"clockwise"`                                        |
| `rings`                  | `readonly ActivityRing[]`                                                                                                                                                                                                                | The rings, inside out. Each has a `key` in `config`, a `value`, and an optional `domain` that its full circle stands for.              |
| `domain?`                | `readonly [number, number] \| undefined`                                                                                                                                                                                                 | The range a full ring stands for, for rings without their own `domain`. Default: `[0, 100]`                                            |

<Caption>
`RadialBarChart` and `RadialBarChart.Series` also take every prop of Recharts' [RadialBarChart](https://recharts.github.io/en-US/api/RadialBarChart/) and [RadialBar](https://recharts.github.io/en-US/api/RadialBar/), like `innerRadius`, `startAngle` and `stackId`.
</Caption>