# Radial Bar Chart

Show progress toward a goal as a ring that fills, or compare a few measures as concentric rings against one maximum.

Seats used on a plan as a progress ring

[Complete TSX file](/examples/radial-bar-chart/default.tsx)

```tsx
"use client";

import { RadialBarChart } from "@/siteplane/components/radial-bar-chart";

export default function Example() {
  return (
    <RadialBarChart
      centerFormat={{ style: "percent" }}
      centerLabel="Seats used"
      centerValue={34 / 50}
      data={[{ id: "seats", label: "Seats used", value: 34 }]}
      formatValue={(value) => `${value} of 50 seats`}
      label="Seats used on the Team plan"
      max={50}
    />
  );
}
```

A Radial Bar Chart draws each value as a bar that fills a ring of its own, from 12 o'clock clockwise, by its share of `max`. One bar makes a progress ring, such as the seats used on a plan; a few bars make concentric rings that measure several goals against the same maximum. Each bar runs over a neutral track with round ends, the hole can hold a figure with a caption, and a card that trails beside the bar under the pointer shows its value.

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/radial-bar-chart
```

With npm: `npx shadcn@4.18.0 add @siteplane/radial-bar-chart`. [Registry JSON](/registry/radial-bar-chart.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/toggle-group
```

## Usage

```tsx
import { RadialBarChart } from "@/siteplane/components/radial-bar-chart";

<RadialBarChart
  label="Seats used"
  data={[{ id: "seats", label: "Seats used", value: 34 }]}
  max={50}
/>;
```

Each bar fills its ring by its share of `max`, 100 by default. A value above `max` fills the whole ring and a value below 0 leaves it empty, while the tooltip still names the value itself.

## Several rings

Pass several bars to draw a ring for each, concentric from the outside in: the first bar is the outer ring. A lone ring is an eleventh of the chart’s size thick, 16 px at `xs` to 28 px at `lg`. Every bar you add thins all the rings, to a seventeenth of the size for three bars, so the hole keeps room for its figure, and the rings stand a quarter of their thickness apart. With more than one bar, a legend below the rings names each bar with its color. Pass `formatValue` to write the values in the tooltip and in what screen readers read, here as a share of each goal.

Three quarterly goals as concentric rings

[Complete TSX file](/examples/radial-bar-chart/rings.tsx)

```tsx
"use client";

import { RadialBarChart } from "@/siteplane/components/radial-bar-chart";

const goals = [
  { id: "revenue", label: "Revenue", value: 82 },
  { id: "customers", label: "New customers", value: 64 },
  { id: "retention", label: "Retention", value: 91 },
];

export default function Example() {
  return (
    <RadialBarChart
      centerFormat={{ style: "percent" }}
      centerLabel="Average"
      centerValue={0.79}
      data={goals}
      formatValue={(value) => `${value}% of goal`}
      label="Quarterly goals reached"
      size="md"
    />
  );
}
```

## Content in the hole

Pass `centerValue` to show a figure in the hole, such as a share or a total, and `centerLabel` for a caption above it. The chart fits the figure into the hole: in the largest text step the hole offers, from 48 px in a hole of 240 px down to 20 px in one of 96 px, or a smaller step where it fits. The figure keeps all its digits in the three largest steps the hole offers and is written in compact notation below them, such as $1.2M; screen readers read it in full, and it rolls to a new value. `centerFormat` takes Intl.NumberFormat options, such as a percentage or a currency, in `locale`. The caption is one line of muted text, 14 px in a hole of 150 px or more and 12 px in a smaller one, and it ends in an ellipsis where the hole is too narrow for it.

Revenue toward a target and a completed setup

[Complete TSX file](/examples/radial-bar-chart/center.tsx)

```tsx
"use client";

import { CheckIcon } from "@phosphor-icons/react/dist/ssr";
import { RadialBarChart } from "@/siteplane/components/radial-bar-chart";

const dollars = {
  currency: "USD",
  maximumFractionDigits: 0,
  minimumFractionDigits: 0,
  style: "currency",
} satisfies Intl.NumberFormatOptions;
const formatDollars = new Intl.NumberFormat("en-US", dollars);

export default function Example() {
  return (
    <div className="flex flex-wrap items-start justify-center gap-x-12 gap-y-10">
      <RadialBarChart
        centerFormat={dollars}
        centerLabel="Revenue"
        centerValue={1_486_000}
        data={[{ id: "revenue", label: "Revenue", value: 1_486_000 }]}
        formatValue={(value) => formatDollars.format(value)}
        label="Revenue toward the annual target of $2,000,000"
        max={2_000_000}
      />
      <RadialBarChart
        center={<CheckIcon aria-hidden="true" className="size-12" />}
        data={[{ id: "setup", label: "Setup steps", value: 6 }]}
        formatValue={(value) => `${value} of 6 done`}
        label="Workspace setup, complete"
        max={6}
      />
    </div>
  );
}
```

For content of your own, such as an icon for a goal that is done, pass `center` instead. It is laid out in the square around the hole and cut off at the hole’s round edge, so it never covers a ring; keep it short. The content in the hole never takes the pointer, and it is not part of the chart’s accessible name, which is `label` alone.

## Sizes

`size` sets the diameter of the outer ring: a size name, `xs` (176 px), `sm` (220 px, the default), `md` (264 px) or `lg` (308 px), or a number of pixels. The rings, the gaps and the steps of the figure follow the size; a lone ring leaves a hole of 144, 180, 216 and 252 px for a figure of 24, 30, 36 and 48 px.

Progress rings at xs, sm, md and lg

[Complete TSX file](/examples/radial-bar-chart/sizes.tsx)

```tsx
"use client";

import { RadialBarChart } from "@/siteplane/components/radial-bar-chart";

const sizes = [
  { name: "xs", pixels: 176 },
  { name: "sm", pixels: 220 },
  { name: "md", pixels: 264 },
  { name: "lg", pixels: 308 },
] as const;

export default function Example() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-x-12 gap-y-10">
      {sizes.map((size) => (
        <div className="grid justify-items-center gap-4" key={size.name}>
          <p className="text-xs text-muted-foreground tabular-nums">
            {size.name}, {size.pixels} px
          </p>
          <RadialBarChart
            centerFormat={{ style: "percent" }}
            centerLabel="Storage used"
            centerValue={0.72}
            data={[{ id: "storage", label: "Storage used", value: 72 }]}
            label={`Storage used, ${size.pixels} pixels`}
            size={size.name}
          />
        </div>
      ))}
    </div>
  );
}
```

## Categorical palette

A bar that names no `color` takes a shade of the brand color, from strong to light, spread over the number of bars, the outer ring strongest. With `palette="categorical"`, each bar takes its own chart color instead, `--chart-1` to `--chart-8` in order, which suits measures that are not parts of one goal. Both palettes start over from the ninth bar, and a `color` on a bar always wins.

## Changing data

When `data` changes, the rings glide to it. Bars are told by their `id`, so give every bar a stable one: a bar that stays glides to its new value, a new bar grows from nothing, and a bar that is gone shrinks away in its ring before the rings close up. When the number of bars changes, the rings take their new thickness and places at once. The legend adds and removes its entries with the list motion of [Motion](/docs/components/motion/), and the tooltip stays on the bar it was on.

Sales targets that glide when the period or the targets change

[Complete TSX file](/examples/radial-bar-chart/changing.tsx)

```tsx
"use client";

import { useState } from "react";
import { RadialBarChart } from "@/siteplane/components/radial-bar-chart";
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@/siteplane/components/toggle-group";

const targets = [
  { id: "calls", label: "Calls booked" },
  { id: "demos", label: "Demos held" },
  { id: "deals", label: "Deals won" },
];

const reached = {
  month: [86, 74, 66],
  week: [41, 53, 19],
};

type Period = keyof typeof reached;

export default function Example() {
  const [period, setPeriod] = useState<Period>("month");
  const [shown, setShown] = useState(() => targets.map((target) => target.id));
  const data = targets.flatMap((target, index) =>
    shown.includes(target.id)
      ? [{ ...target, value: reached[period][index] ?? 0 }]
      : [],
  );

  return (
    <div className="grid w-full max-w-md gap-4">
      <ToggleGroup
        aria-label="Period"
        onValueChange={(next) => {
          if (next[0]) setPeriod(next[0] as Period);
        }}
        size="sm"
        value={[period]}
        variant="outline"
      >
        <ToggleGroupItem value="week">This week</ToggleGroupItem>
        <ToggleGroupItem value="month">This month</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup
        aria-label="Targets"
        multiple
        onValueChange={(next) => setShown(next)}
        size="sm"
        value={shown}
        variant="outline"
      >
        {targets.map((target) => (
          <ToggleGroupItem key={target.id} value={target.id}>
            {target.label}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <RadialBarChart
        data={data}
        formatValue={(value) => `${value}% of target`}
        label="Sales targets reached"
      />
    </div>
  );
}
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| RadialBarChart.data | readonly RadialBarChartDatum[] | required | The bars, one ring each, from the outer ring inward. |
| RadialBarChart.label | string | required | Accessible name of the chart. |
| RadialBarChart.aria-describedby | string | unset | Id of an element that describes the chart, read after the description that the chart gives itself. |
| RadialBarChart.max | number | 100 | The value of a full ring. Each bar fills its ring by its share of it, from 12 o’clock clockwise; a value above it fills the ring and one below 0 leaves it empty. A max that is not a positive number counts as 100. |
| RadialBarChart.size | xs \| sm \| md \| lg \| number | sm | Diameter of the outer ring: xs 176 px, sm 220 px, md 264 px and lg 308 px, or a number of pixels. |
| RadialBarChart.centerValue | number | unset | A figure in the hole, such as a share or a total. The chart fits it in the largest text step the hole offers, from 48 px down to 20 px, or a smaller one, and writes it compact where it does not fit in full. Screen readers read it in full. |
| RadialBarChart.centerLabel | string | unset | A caption above centerValue: one line of muted text, 14 px in a hole of 150 px or more and 12 px in a smaller one, that ends in an ellipsis where the hole is too narrow. |
| RadialBarChart.centerFormat | Intl.NumberFormatOptions | unset | How centerValue is written in locale, such as a percentage or a currency. The chart adds the compact notation when the figure needs it. |
| RadialBarChart.center | ReactNode | unset | Content of your own in the hole, in place of centerValue and centerLabel, cut off at the hole’s edge so it never covers a ring. It never takes the pointer and is not part of the accessible name. |
| RadialBarChart.legend | boolean | true with more than one bar | Lists the bars below the rings, each with its color, and reads each value to screen readers. Without it the bars and their values are the description of the chart. |
| RadialBarChart.palette | brand \| categorical | brand | brand shades the brand color from strong to light, the outer ring strongest; categorical gives each bar its own chart color. A bar’s own color wins either way. |
| RadialBarChart.formatValue | (value: number) => string | locale number (1,234.5) | Formats the value in the tooltip and in the text that screen readers read for each bar, from the legend or the description of the chart. |
| RadialBarChart.rollingNumbers | boolean | false | Rolls the value in the tooltip to the next bar’s. Off, it changes at once. centerValue rolls to a new value either way. |
| RadialBarChart.locale | string | provider, else en-US | Locale of the numbers: the locale of SiteplaneLocaleProvider unless set, and en-US without one, so the server and the browser agree. |
| RadialBarChart.emptyLabel | string | No data | Shown in the hole when there is no bar to draw. The chart then keeps one empty ring. Unset, it is the noData text of the chart messages of SiteplaneLocaleProvider. |
| RadialBarChart.labels | Partial<ChartLabels> | English words | Replaces the words that the chart gives screen readers for this chart, each one on its own. Translate them once for every chart with the chart messages of SiteplaneLocaleProvider. |
| RadialBarChart.className | string | unset | Additional classes on the figure. |
| RadialBarChartDatum.id | string | required | Stable key of the bar. It tells the chart which bar is which when the data changes. |
| RadialBarChartDatum.label | string | required | Name shown in the legend and the tooltip. |
| RadialBarChartDatum.value | number | required | Value of the bar, drawn as its share of max. A value that is not a finite number counts as 0. |
| RadialBarChartDatum.color | string | palette color | A CSS color that replaces the palette color of this bar. |
| ChartLabels.roleDescription | string | chart | What screen readers call the chart. |
| ChartLabels.keyboardHint | string | Use the arrow keys to move between data points. | Read after the description of the chart while it is a focus stop. An empty text leaves the hint out. |
RadialBarChartProps, RadialBarChartDatum and RadialBarChartSize export these
contracts, and ChartLabels comes from the chart core,
`@/siteplane/components/chart`, which installs with the chart. The chart renders
a figure with the rings and, for several bars, the legend; it takes no native
props or ref beyond `className` and `aria-describedby`. Each ring is a track in
the neutral color of an empty share with its bar over it. The bar under the
pointer or the keyboard carries `data-active`, and the figure in the hole
carries `data-size` with its text step and `data-compact` while it is written
compact.

[Read the installed source](/source/radial-bar-chart).

## Usage notes

Use a radial bar chart for progress toward a goal, such as storage used or a quota, or for up to three or four measures against one maximum. It shows how far each value has come, not how values compare across many categories; for those, a [Bar Chart](/docs/components/bar-chart/) or a [Bar List](/docs/components/bar-list/) reads better. To show how one total divides into shares, use a [Pie Chart](/docs/components/pie-chart/). When readers need a value at a glance without a ring, a [Progress](/docs/components/progress/) bar takes less room.

The chart is one focus stop. Keyboard focus makes the outer bar active; the Left and Right arrow keys step from ring to ring and stop at the outer and the inner ring, Home and End jump to them, and Escape closes the tooltip. A mouse finds the ring under the pointer, half the gap on each side included, and a tap or pen press pins the bar under it until the next press elsewhere or Escape. The card shows the bar’s value and name, sits beside the middle of the bar and stays inside the window. Screen readers meet the rings as a chart named by `label` and hear a hint that the arrow keys move between the data points; `labels` replaces the hint and the role description, for example with their translation. While the keyboard or a tap moves between the bars, a polite live region reads each bar and its value. The legend names every bar and reads its formatted value to screen readers, so the color never carries the information alone; without the legend, the same text describes the chart. A chart with nothing in it is not a focus stop, and `emptyLabel` describes it. Legend entries are not focus stops, and the legend does not toggle bars.

Nothing fades while a bar is active: in the brand shades, a faded bar would look like another one. The chart has no click or selection API. New data animates with the [Motion](/docs/components/motion/) tokens (`--motion-duration-value` and `--motion-ease-standard`), and the tooltip card trails the bar with `--motion-duration-follow-trail`. All of it is instant under reduced motion: the system setting, `html` with `data-motion-reduce="true"` or `SiteplaneMotionProvider preset="reduced"`. The tooltip comes from [Tooltip](/docs/components/tooltip/). The chart opens and closes it itself, so it needs no `TooltipProvider`, which only shares hover delays between tooltips.
