Siteplane UI

Radial Bar Chart

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

Markdown
Seats used68%
Use the arrow keys to move between data points.
Seats used: 34 of 50 seats.
"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

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

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

Usage

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.

Average79%
Use the arrow keys to move between data points.
  • Revenue: 82% of goal
  • New customers: 64% of goal
  • Retention: 91% of goal
"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$1,486,000
Use the arrow keys to move between data points.
Revenue: $1,486,000.
Use the arrow keys to move between data points.
Setup steps: 6 of 6 done.
"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.

xs, 176 px

Storage used72%
Use the arrow keys to move between data points.
Storage used: 72.

sm, 220 px

Storage used72%
Use the arrow keys to move between data points.
Storage used: 72.

md, 264 px

Storage used72%
Use the arrow keys to move between data points.
Storage used: 72.

lg, 308 px

Storage used72%
Use the arrow keys to move between data points.
Storage used: 72.
"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, and the tooltip stays on the bar it was on.

Use the arrow keys to move between data points.
  • Calls booked: 86% of target
  • Demos held: 74% of target
  • Deals won: 66% of target
"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

Component properties
PropTypeDefaultDescription
RadialBarChart.datareadonly RadialBarChartDatum[]requiredThe bars, one ring each, from the outer ring inward.
RadialBarChart.labelstringrequiredAccessible name of the chart.
RadialBarChart.aria-describedbystringunsetId of an element that describes the chart, read after the description that the chart gives itself.
RadialBarChart.maxnumber100The 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.sizexs | sm | md | lg | numbersmDiameter of the outer ring: xs 176 px, sm 220 px, md 264 px and lg 308 px, or a number of pixels.
RadialBarChart.centerValuenumberunsetA 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.centerLabelstringunsetA 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.centerFormatIntl.NumberFormatOptionsunsetHow centerValue is written in locale, such as a percentage or a currency. The chart adds the compact notation when the figure needs it.
RadialBarChart.centerReactNodeunsetContent 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.legendbooleantrue with more than one barLists 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.palettebrand | categoricalbrandbrand 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) => stringlocale 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.rollingNumbersbooleanfalseRolls the value in the tooltip to the next bar’s. Off, it changes at once. centerValue rolls to a new value either way.
RadialBarChart.localestringprovider, else en-USLocale of the numbers: the locale of SiteplaneLocaleProvider unless set, and en-US without one, so the server and the browser agree.
RadialBarChart.emptyLabelstringNo dataShown 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.labelsPartial<ChartLabels>English wordsReplaces 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.classNamestringunsetAdditional classes on the figure.
RadialBarChartDatum.idstringrequiredStable key of the bar. It tells the chart which bar is which when the data changes.
RadialBarChartDatum.labelstringrequiredName shown in the legend and the tooltip.
RadialBarChartDatum.valuenumberrequiredValue of the bar, drawn as its share of max. A value that is not a finite number counts as 0.
RadialBarChartDatum.colorstringpalette colorA CSS color that replaces the palette color of this bar.
ChartLabels.roleDescriptionstringchartWhat screen readers call the chart.
ChartLabels.keyboardHintstringUse 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.

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 or a Bar List reads better. To show how one total divides into shares, use a Pie Chart. When readers need a value at a glance without a ring, a 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 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. The chart opens and closes it itself, so it needs no TooltipProvider, which only shares hover delays between tooltips.