Radial chart

Progress rings, full or half, with goals and honest overflow. Same props on both engines.

Bar chart Line chart Area chart Composed chart Donut chart Radial chart Radar chart Sankey chart Heatmap Scatter chart Waterfall chart Treemap Funnel chart KPI stat Gauge

Install

Pick one engine. Both builds take the same props, so switching later changes only the import path.

Recharts

npx shadcn@latest add https://beautifulcharts.dev/r/instrument-radial-chart-recharts.json

import { RadialChart } from "@/components/beautiful-charts/themes/instrument/recharts/radial-chart";
npm dependencies: recharts@^3.10.1

Apache ECharts

npx shadcn@latest add https://beautifulcharts.dev/r/instrument-radial-chart-echarts.json

import { RadialChart } from "@/components/beautiful-charts/themes/instrument/echarts/radial-chart";
npm dependencies: echarts@^6.1.0

Example

A complete client module. Paste it into your app after installing the Recharts build; for ECharts, change recharts to echarts in the import. To pick options visually and copy the matching code, use the Customizer.

"use client";

import { RadialChart } from "@/components/beautiful-charts/themes/instrument/recharts/radial-chart";

const data = [
  { goal: "Onboarding", done: 86, target: 90 },
  { goal: "Activation", done: 64, target: 70 },
  { goal: "Retention", done: 41, target: 60 },
];

export function QuarterGoals() {
  return <RadialChart data={data} nameKey="goal" valueKey="done" goalKey="target" max={100} title="Quarter goals" valueFormatter={(v) => `${v}%`} />;
}

Radial chart props

Generated from RadialChartProps in the installed source, so this table and your editor's hints always agree. * marks a required prop.

Radial chart props
Prop	Type	Description
nameKey*	keyof TDatum & string	The field naming each ring.
valueKey*	keyof TDatum & string	The field holding each ring's value.
max	number	The full-ring value for every ring (default 100), or a field holding each ring's own maximum.
maxKey	keyof TDatum & string	A field holding each ring's own maximum. Wins over `max`.
goal	number	A goal for every ring, or a field holding each ring's goal. Drawn as a tick across the ring.
goalKey	keyof TDatum & string	A field holding each ring's own goal. Wins over `goal`.
variant	"full" \| "semi"	"full" (a circle) or "semi" (a half circle opening downward).
thickness	number	Ring thickness as a share of the space per ring, 0.2–1.
rounded	boolean	Rounded ring ends.
track	boolean	Draw the unfilled track behind each ring.
center	false \| { label?: string }	What the centre shows: the first ring's share of its max, or nothing.

Recharts build only

Native Recharts children render inside the chart with your original rows, so ReferenceArea, Label or a custom Customized layer work as they do in any Recharts chart.

Recharts build props
Prop	Type	Description
children	ReactNode	Recharts children render inside the same RadialBarChart, which receives your original rows.

Apache ECharts build only

Escape hatches into the engine. Your option is deep-merged over the generated one, so you can change one nested setting without replacing a whole section.

Apache ECharts build props
Prop	Type	Description
renderer	EChartsRenderer	"canvas" (default) or "svg".
option	OptionOverride	Deep-merged over the generated option, or `(generated) => option`. The rings are one custom series (id "rings", one data item per ring).

Series config

One entry per series key in config. shadcn's ChartConfig entries work as they are. Give a series at most one of color, theme or colors; TypeScript rejects more than one. This table lists only the options this chart reads.

Radial chart series config
Prop	Type	Description
label	ReactNode	Name shown in the legend, tooltip and table. Defaults to the key, humanised.
ariaLabel	string	Plain text for tables, summaries and announcements when `label` is not a string.
icon	ComponentType<{ className?: string }>	An icon component (e.g. from lucide-react) shown in place of the swatch in the legend and tooltip.
format	(value: number) => string	Formats this series' values everywhere: tooltip, legend, table, readout.
color	ColorValue	One colour: any CSS colour or var(--chart-1), or `{ light, dark }`.
theme	never	shadcn's per-theme colours, `{ light, dark }`.
colors	never	Gradient stops from base to value end, per theme. The last stop is the series' single colour.

Events

Every callback, and the payload types it receives. Indexes always point into the data you passed, even when a brush or grouping shows a subset.

Radial chart events
Prop	Type	Description
onSelectedChange	(selection: Selection<TDatum> \| null) => void	Called when a row is selected or cleared, by pointer, keyboard or the data table.
onHiddenChange	(hidden: string[]) => void	Called when the legend hides or shows a series.
onActiveChange	(index: number \| null) => void	Called as the hovered or focused row changes, or null when it leaves.
onReady	(chart: EChartsType) => void	Called once with the ECharts instance, e.g. to add event listeners.

export type Selection<TDatum> = {
  /** Index into the data you passed in, even when a brush shows a subset. */
  dataIndex: number;
  datum: TDatum;
  seriesKey: string | null;
  source: "pointer" | "keyboard" | "table";
  /** For a grouped segment (a donut's "Other"): the indexes of every row it stands for. `dataIndex` is the largest. */
  members?: number[] | undefined;
};

export type TooltipContext<TDatum> = {
  datum: TDatum;
  /** Index into the data you passed in. */
  dataIndex: number;
  /** Visible series at this index. `value` is your raw value; `share` is its part of the row in 100% mode. */
  series: { key: string; label: ReactNode; value: number | null; share?: number | null | undefined; color: string; selected: boolean }[];
};

Parts and styling hooks

Each part carries a data-slot attribute. Theme rules inside the chart are one attribute selector deep, so a selector such as .my-chart [data-slot="chart-title"] overrides them. These are the slots in the files this chart installs; parts a chart doesn't use are simply absent from its markup.

chartchart-bodychart-descriptionchart-eyebrowchart-footerchart-headerchart-headingchart-legendchart-legend-itemchart-legend-labelchart-legend-swatchchart-legend-valuechart-livechart-mainchart-plotchart-readoutchart-statchart-stat-notechart-stat-valuechart-statechart-state-boxchart-state-messagechart-statschart-tablechart-table-scrollchart-takeawaychart-titlechart-tooltipodometerodometer-digitodometer-glyphsodometer-reelodometer-signpartial-notereadout-deltareadout-unitreadout-valuesr-onlytooltip-indicatortooltip-memberstooltip-rowtooltip-titletooltip-value

Props every chart shares

Header, states, legend, tooltip, formatting, motion, sound and controlled interaction state. They work the same on every Instrument chart and both engines. The guide explains colours, controlled state and accessibility.

Show all 32 shared props

Props every chart shares
Prop	Type	Description
data*	TDatum[]	Your rows, as they are. Missing values (null, undefined, NaN) stay missing and are never drawn as zero.
locale	string	BCP 47 locale. Defaults to "en-US" so server and client render the same text.
timeZone	string	IANA time zone for dates. Defaults to "UTC" so server and client agree.
config	ChartConfig	Per-series label, colour, icon, format and style, keyed by series key. shadcn ChartConfig works as it is.
eyebrow	ReactNode	Small label above the title.
title	ReactNode	Card title. A string also names the chart for screen readers.
description	ReactNode	A line under the title.
takeaway	ReactNode \| ((summary: string) => ReactNode) \| false	The sentence under the title. Computed from the data by default; pass text, a function of the computed sentence, or false to hide it.
ariaDescription	string	Accessible summary for screen readers. Computed from the data by default.
motion	MotionPreference	"full" (default), "subtle" or "off". Reduced-motion settings always win.
motionOptions	MotionOptions	When the entrance plays.
sound	boolean	Sound cues on hover, scrub and select. Plays only if the visitor has also turned sound on for the page.
density	Density	"comfortable" (default) or "compact" for dashboards.
legend	LegendOptions \| false	Legend position, alignment, shape and click action, or false to hide it.
tooltip	TooltipOptions<TDatum> \| false	Tooltip position, indicator, cursor and custom content, or false to turn it off.
valueFormatter	(value: number) => string	Values formatted for display. Series formatters in config win.
loading	boolean	Show the loading state. Over existing data, the old marks stay dimmed instead of vanishing.
error	string \| null	An error message. Shows the error state in place of the plot.
emptyState	ReactNode	Shown instead of the plot when there is no data.
loadingState	ReactNode	Shown while `loading` is true and there is no data yet.
errorState	ReactNode	Shown when `error` is set.
selected	number \| null	Controlled and uncontrolled interaction state. Point selection (`selected`) pins one row by its index in `data`. Series selection (`selectedSeries`) picks one series and dims the others. They are separate: picking a row doesn't pick a series.
defaultSelected	number \| null	Initial selected row when uncontrolled.
hidden	string[]	Controlled hidden series keys.
defaultHidden	string[]	Series hidden at first when uncontrolled.
activeIndex	number \| null	Controlled hover or focus index, for syncing several charts on one cursor.
palette	"theme" \| "shadcn"	Series colours: "theme" (default) uses the theme's designed palette; "shadcn" uses your --chart-1..5. --bc-series-N always wins. You can also opt a whole section in with the class bc-use-shadcn-colors.
table	boolean	Show the "Show data table" disclosure. On by default.
stats	ChartStat[]	A row of figures under the title, for dashboard cards and blocks.
footer	ReactNode	A line or action at the bottom of the card, e.g. a source note or a link.
className	string	Classes on the card, for spacing and layout.
height	number	Height of the plot area in px. The frame sizes around it.