Radial Bar Chart
Show progress toward a goal as a ring that fills, or compare a few measures as concentric rings against one maximum.
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-chartComplete 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-groupUsage
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.
- Revenue: 82% of goal
- New customers: 64% of goal
- Retention: 91% of goal
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.
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
sm, 220 px
md, 264 px
lg, 308 px
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.
- Calls booked: 86% of target
- Demos held: 74% of target
- Deals won: 66% of target
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Radial | readonly RadialBarChartDatum[] | required | The bars, one ring each, from the outer ring inward. |
Radial | string | required | Accessible name of the chart. |
Radial | string | unset | Id of an element that describes the chart, read after the description that the chart gives itself. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | (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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | 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. |
Radial | string | unset | Additional classes on the figure. |
Radial | string | required | Stable key of the bar. It tells the chart which bar is which when the data changes. |
Radial | string | required | Name shown in the legend and the tooltip. |
Radial | number | required | Value of the bar, drawn as its share of max. A value that is not a finite number counts as 0. |
Radial | string | palette color | A CSS color that replaces the palette color of this bar. |
Chart | string | chart | What screen readers call the chart. |
Chart | 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.
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.