# Radial Chart

Radial chart for progress against a goal: radial bars, a stacked ring, a progress ring and activity rings.

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

## Install

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

## Import

```tsx
import { RadialChart, RadialChartProps, RadialChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

const data = [
  { name: "Chrome", value: 78 },
  { name: "Safari", value: 61 },
  { name: "Firefox", value: 34 },
]

export function BrowserShare() {
  return <RadialChart data={data} index="name" max={100} label="Browser share" />
}
```

Expected result: You should see three concentric rings, the outer one the longest. Hovering a ring shows its value in the centre.

## When to use

### Use Radial Chart for

- Progress against a goal, one ring per row
- A single completion ring with a number in the middle
- Concentric rings of different targets, as in an activity view

### Use something else

- [Progress Chart](https://wunderui.com/components/progress-chart) for quotas as horizontal meters or a waffle
- [Gauge Chart](https://wunderui.com/components/gauge-chart) for one value on a scale with bands
- [Pie Chart](https://wunderui.com/components/pie-chart) for shares of one whole
- [Bullet Chart](https://wunderui.com/components/bullet-chart) for a measure against a target and ranges

## Keyboard

The plot is focusable: Arrow keys step through the rings and the live region announces each one with its value.

| 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 ring. 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 ring. |
| `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.

- **Rings:** Data rows are the rings, outermost first. Each ring is read against the max (default 100), so a full circle is 100 percent of its own target.
- **Centre number:** The centre shows the first row at rest (the total on the stacked variant) and the hovered ring while you point at one. A formatter replaces the percent and a centre label sets the text under it.
- **Stacked ring:** The stacked variant opens the ring at the bottom and splits the arc into segments, one per row.
- **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.

- **Draw-in:** Rings are drawn along their arc when the chart first comes into view, after loading and when new data arrives. The animation can be turned off.
- **Hover:** The ring under the pointer stays, the others dim, and the centre counts to its value.
- **Reduced motion:** With reduced motion on, the chart appears at once without the enter sequence. The tooltip and every state still work.

## Anatomy

- `RadialChart`: Pass data with the row name and value fields. The max is the value of a full ring (default 100), the centre label is the text under the centre number, and rings follow the row order, outermost first.
- `Plot`: The focusable region. Arrow keys step through the rings and announce each one with its value.
- `Marks`: Two phases on first view: the tracks bloom, then the value arcs draw along them. Ring width and gap come from one formula for every ring count. The ring under the pointer stays, the others dim, and the centre counts to its value.
- `Centre number`: The percentage of the hovered ring; at rest the first row (radial bars and progress ring) or the total (stacked ring). It counts up as the chart enters and its size follows the free space inside the rings. A custom formatter replaces the default percent.
- `Tooltip`: The row name and its value for the ring under the pointer.
- `Loading, empty and error`: One muted ring on the progress and stacked variants, three concentric rings on the others, with the shimmer over them. The same shape sits faintly behind the empty and error messages.
- `Data table and live region`: A table of the rows and values for screen readers, with the live region for the active ring.

## Best practices

### When to use

- Use RadialChart for a few progress values against targets, like the rings of an activity summary. Use GaugeChart for one value on a scale and ProgressChart for rows as bars.

### Do

- Keep to three or four rings. Inner rings are short, so a fifth ring is too small to compare with the first.
- Set the max per chart, not per ring. Rings with different maxima read as if they shared a scale, so show the target in the label if targets differ.
- Order rings by importance, outermost first, and name each in the legend or tooltip. Colour alone does not tell the rings apart.

### Don't

- Don't use rings for values above 100 percent of the target. The arc stops at a full circle, so show an overshoot in the number.
- Don't use the stacked variant as a pie with a gap. It is for parts of one total in a three-quarter arc, with the sum in the centre.

## API reference

### RadialChart

| 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 |  |  |
| centerLabel | string |  | Small text under the centre 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. |
| 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. |
| label | string |  | Accessible name, e.g. the card title. |
| max | number | 100 | Value of a full ring (default 100). |
| 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" \| "heat" \| "success" | "series" | A colour ramp that follows each ring's sweep: heat runs from green to red (load, temperature), success from red to green (progress towards a goal). The centre number stays in the foreground colour. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| tooltip | boolean |  |  |
| value | string |  | Field holding the value. Default "value". |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "radial-bar" \| "radial-stacked" \| "progress-ring" \| "multi-ring-progress" | "radial-bar" | Figma variant. Default `radial-bar`. |
| width | number |  |  |

## Examples

### States

### Colour ramps

### Ring count

## In context

### Storage Usage Ring

Used storage as a ring, usage by service next to it.

### Activity Rings

Move, exercise and stand rings with the day's numbers.

### Customer Health Score

Accounts by health on one ring, and the accounts to watch.

## For AI agents

`get_component("radial-chart")`

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