# Sunburst

Sunburst for a hierarchy as rings, or as circle packing.

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

## Install

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

## Import

```tsx
import { SunburstChart, SunburstChartProps, SunburstChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

const data = {
  name: "Revenue",
  children: [
    { name: "Software", children: [{ name: "Core", value: 340 }, { name: "Pro", value: 260 }] },
    { name: "Services", children: [{ name: "Support", value: 150 }] },
  ],
}

export function RevenueMix() {
  return <SunburstChart data={data} centerLabel="revenue" label="Revenue by product line" />
}
```

Expected result: You see two rings, the outer one split into three segments, with the total in the centre.

## When to use

### Use Sunburst for

- A hierarchy as rings, where each ring is a level
- The total in the centre, and the value of the part you hover
- Nested circles (circle packing) for a hierarchy without a total

### Use something else

- [Treemap](https://wunderui.com/components/treemap) for many small leaves that need more room
- [Pie Chart](https://wunderui.com/components/pie-chart) for one level of shares
- [Network Chart](https://wunderui.com/components/network-chart) for an organisation chart as a tree
- [Radial Chart](https://wunderui.com/components/radial-chart) for progress against a goal

## Keyboard

The plot is focusable. Arrow keys walk the parts and the live region reads each with its path, value and share of the top-level total.

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

- **Data:** The data is a hierarchy tree. Segments are sized by value and coloured by their top-level group.
- **Centre:** The sunburst shows the total, or the value of the hovered part, with a label under it (default total). Circle packing has no centre.
- **Frame:** The frame is square and hugs its card. You can set its height (default 360).
- **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 jumps. Add a retry handler to show a Try again button on error.
- **Legend:** A ChartCard shows the series as badges. With two or more series each badge switches its series off, but the last visible one stays on.
- **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 library's motion tokens.

- **Sweep:** Ring segments sweep in clockwise and the centre counts up when the chart first comes into view, after loading, when the data changes and after a zoom. You can turn it off.
- **Hover:** The hovered part, its ancestors and its descendants keep their strength, the rest dims, and the centre counts to the hovered value.
- **Reduced motion:** With reduced motion the chart appears at once. The tooltip, the crosshair and every state still work.

## Anatomy

- `SunburstChart`: Takes a hierarchy tree as its data. You can set the text under the centre value (default total), fade groups and set the frame height (default 360).
- `Plot`: The focusable region. Arrow keys walk the parts and the live region reads each with its path, value and share of the top-level total, like Hardware › Devices: 180, 12.3% of the total.
- `Marks`: Ring segments that sweep in clockwise, sized by value, in the colour of their top-level group. Hovering a part keeps it, its ancestors and its descendants and dims the rest. With zoomable, a click on a part zooms into it. Circle packing draws a circle per node and nests the children inside.
- `Centre`: The total, or the value of the hovered part, with a label under it, counted up as the chart enters and sized by the hole. When zoomed it shows the part in focus; a click on it goes back. Only the sunburst has a centre, circle packing does not.
- `Tooltip`: The path of the part with its value and its share of the total.
- `Loading, empty and error`: A muted ring on the sunburst and a muted disc on circle packing, under the shimmer.
- `Data table and live region`: A hidden table of every node with its path and value.
- `Chart Zoom Out`

## Best practices

### When to use

- Use it when the hierarchy itself is the story, for example product, plan and region. For one level of shares use PieChart, and for many leaves TreemapChart.

### Do

- Keep it to three levels. Outer rings of many small segments can't be labelled or hovered.
- Set the centre label to what the total counts, such as orders or GB, so the centre number isn't read as a percentage.
- Use circle packing when the nesting matters more than the proportions, and keep leaf values positive.

### Don't

- Don't compare segments on different rings by angle. A child's angle is relative to its parent, so use the table for exact values.
- Don't use it for a flat list. A PieChart or BarChart is simpler and easier to read.

## API reference

### SunburstChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | HierarchyDatum |  |  |
| 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 | "total" | Text under the centre value (sunburst). Default "total". |
| className | string |  | Extra classes for the root element of the chart. |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| description | string |  |  |
| height | number | 360 |  |
| hiddenSeries | readonly string[] |  |  |
| label | string |  |  |
| 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. |
| onZoomChange | (path: string) => void |  | Called with the path of the part in focus, like Software › Pro, or an empty string for the whole hierarchy. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "basic-sunburst" \| "circle-packing" | "basic-sunburst" | Figma variant. Default `basic-sunburst`. |
| width | number |  |  |
| zoomable | boolean | false | Click a part with children (or press Enter on it) to zoom into it; a click in the centre or Escape goes back up one level. The rings sweep in again after each zoom. |

## Examples

### States

### Path highlight and zoom

## In context

### Revenue Mix

Revenue by line and product, with the totals.

## For AI agents

`get_component("sunburst")`

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