RareCharts provides three circular chart types that share a common API and theme system: Donut, Pie, and Gauge. Each answers a different question.
Donut
The default circular chart. A ring with a center area — the center gives you a place to put something useful: the total, a headline number, or a short label. That makes donut the better default for dashboards, where charts rarely live alone and context matters.
const d3 = RareCharts.d3; // the bundled D3
new RareCharts.Donut('#chart', {
title: 'Revenue by Product',
source: 'Source: Internal accounting',
legend: segments.map(d => ({ label: d.label, type: 'bar' })),
height: 300,
centerText: data => '$' + d3.format(',.0f')(d3.sum(data, d => d.value)),
centerLabel: 'Revenue',
}).setData(segments);
Legend to the right
Pass legendPosition: 'right' to place the legend in a vertical column beside the chart instead of above it. Works well when you have many categories or want to keep the chart area compact.
new RareCharts.Donut('#chart', {
legend: segments.map(d => ({ label: d.label, type: 'bar' })),
legendPosition: 'right',
height: 340,
}).setData(segments);
Either way the legend items need no color: the chart paints each dot, line or band in the color of the slice with the same label — or the same id, when the item has one — so the items may come in any order. An item whose slice is not in the ring (a zero value, a level you drilled away from) keeps the theme accent, and an item with its own color keeps that.
An item that names a slice also hides and shows it: a click toggles it, a double click keeps it alone, Show all brings all back. The ring closes over the slices shown, and the total, the percents and the centre are theirs; with legendRescale: false a hidden slice leaves its gap and the percents stay of every slice. setSeriesVisible(names | null) takes slice ids, else labels. With a tree (drill-down) the legend is a static key. A Gauge has no series: its legend is a caption. More: Interactive legend.
Drill-down (hierarchy mode)
Hand Donut a tree — a single root object instead of a flat array — and it becomes an interactive drill-down. It opens on the root’s direct children; click a slice that has children to descend into it, and click the center (or a breadcrumb crumb) to come back up — once you are in, the center is a button, so Tab and Enter take you up as well. A leaf slice just shows its value. It is the same tree contract as the hierarchical bar — one data shape, two views: the bar lays the whole hierarchy out at once, the donut walks it one ring at a time.
Two composition details carry over from the tree contract. A parent whose children don’t add up to its stated value has a remainder — the undisclosed gap — which draws as a muted slice once you surface it with showRemainder: true or a per-node remainderLabel. And a named-but-undisclosed item (value: null) has no magnitude, so it cannot be a slice; the ring notes it as “N not disclosed” beneath the chart instead. A parent with no value of its own whose children are all undisclosed is undisclosed too — noted the same way, never drawn as an empty slice. See the hierarchical bar page for the full node shape and the value tri-state.
new RareCharts.Donut('#chart', {
showRemainder: true,
}).setData({
label: 'Portfolio', value: 1400,
children: [
{ label: 'World Liberty Financial', value: 536.4, remainderLabel: 'Other', children: [
{ label: 'Ethereum Key', value: 106 },
{ label: 'USDC Key', value: 56 },
] },
{ label: 'Stablecoin proceeds', value: 196.9 },
{ label: 'NFT INT, LLC', value: null }, // undisclosed → noted, not drawn
],
});
From code: chart.drillUp() goes one level up, and chart.drillToDepth(i) jumps to the i-th crumb of the breadcrumb (0 is the root). Both return the chart and do nothing at the root or on flat data. chart.drillTo(child) is the step a click on a slice takes: it descends into a child of the level shown — pass the object you gave setData, its id, or its label — and draws that level as a click does, remainder and undisclosed items included. A child without disclosed children (a leaf, a remainder), or one not in the level shown, is ignored. It returns the chart too.
To follow the level shown — a details panel next to the ring, a URL hash — pass onDrill. It is called after every change of level, from a click on a slice, the center or a breadcrumb, Enter or Space on the center, or one of the methods above, and the chart has already drawn the new level by then. It receives { node, path, depth, event }: node holds the focused node’s own fields as you gave them, without children; path the same for every level from the root; depth is 0 at the root; event is the click or the key press, or null when a method made the change. It is not called by setData, nor by a method that changes nothing (drillUp() at the root, drillTo a leaf).
new RareCharts.Donut('#chart', {
onDrill: ({ node, path }) => {
details.textContent = path.map(n => n.label).join(' › ') + ': ' + node.value;
},
}).setData(tree);
Pie
A pie is a donut with innerRadius: 0, and that is what Pie draws by default: no hole, no center text, slightly tighter slice gaps. Every other Donut option and method works the same, drill-down included — a pie has no center to click, so you go back up through the breadcrumb; an explicit innerRadius still makes a hole.
A pie chart is a blunt instrument: it answers “how is the total split” when there are only a few categories and the differences are obvious. It breaks down quickly when slices are similar in size, when there are many categories, or when the reader needs precision.
new RareCharts.Pie('#chart', {
height: 300,
showLabels: true,
}).setData(segments);
Outer labels
Enable with showLabels: true. Each slice gets a leader line and two-line text (category name + percent). Slices below labelMinPct (default: 4%) are skipped automatically. A name too long for the room beside the chart makes the ring a little smaller (by up to a quarter) so it fits whole; if even that is not enough, as on a phone, the ring keeps its size, the name is cut with an ellipsis, and the tooltip shows it in full.
Control what appears with labelContent:
'both'— category name + percentage (default)'label'— category name only'percent'— percentage only
new RareCharts.Pie('#chart', {
showLabels: true,
labelContent: 'percent', // just percentages
labelMinPct: 0.05, // hide labels below 5%
}).setData(segments);
Gauge
An arc-based progress chart. Shows a value relative to a maximum along a partial arc. Use it for goal completion, budget usage, KPI progress — anywhere the question is "how far along are we?" A gauge centres its title, subtitle and source over the dial.
setData() accepts a plain number, or an object to override max and min for that call only — the next setData starts again from the max and min options:
// 73 out of 100 (default max)
const gauge = new RareCharts.Gauge('#gauge-progress', {
centerLabel: 'Complete',
}).setData(73);
// 50 achieved out of 80 plan — fills to 62.5%
new RareCharts.Gauge('#gauge-target', {
max: 80,
color: '#00c97a',
centerText: (value, max) => `${value}/${max}`,
centerLabel: 'Achieved',
}).setData(50);
// Override max for this call — 50 of 80
gauge.setData({ value: 50, max: 80 });
// Back to the options — 40 of 100
gauge.setData(40);
A value outside min…max fills the arc to its end (or leaves it empty); the tooltip and centerText still receive the raw value.
The arc geometry is fully configurable:
new RareCharts.Gauge('#chart', {
startAngle: -Math.PI * 0.75, // -135° (default)
endAngle: Math.PI * 0.75, // +135° (default, 270° sweep)
thickness: 0.18, // ring thickness as fraction of radius
cornerRadius: 6,
trackColor: '#e8e8e8', // background arc
color: '#ff3b5c', // fill arc
});
Speedometer — half-circle and needle
Two ingredients make the automotive-indicator look:
- Sweep.
startAngle/endAngleset the arc in radians, clockwise from 12 o'clock. The default±Math.PI * 0.75is a 270° horseshoe;-Math.PI / 2 … Math.PI / 2is the flat 180° half-circle. The gauge re-centers vertically for any sweep and reserves room for the center text when the arc is shallow, so nothing clips. - Needle.
needle: truedraws a pointer pivoting on a hub at the dial center, animated to the value together with the fill. The center readout moves below the hub, dial-style. Color it withneedleColor(default: theme text).
new RareCharts.Gauge('#chart', {
startAngle: -Math.PI / 2, // 9 o'clock
endAngle: Math.PI / 2, // 3 o'clock — a 180° sweep
needle: true,
max: 240,
centerText: v => v,
centerLabel: 'km/h',
}).setData(87);
Data format
Donut and Pie use the same segment data structure (Gauge takes a number — see Gauge above):
[
{ label: 'Subscriptions', value: 42000, color: '#00c97a' },
{ label: 'Services', value: 18000 },
{ label: 'Other', value: 6000 }
]
Only positive finite values are rendered. Zero and negative values are filtered out.
Slices are matched across updates by id, else by label; slices that share a label are matched in order, so each keeps its own slice — give them an id when their order can change. Every update repaints the ring: a new color in setData shows, and a palette color moves with its slice’s position.
Passing a single root object instead of a flat array switches Donut into drill-down mode, where the data is a tree — see the Drill-down section above.
Colors can be provided per item. If omitted, the chart uses the active theme palette in order.
Slice geometry
padAngle controls the gap between slices (a small default keeps separation without turning the chart into a flower). cornerRadius rounds slice corners. Both have sensible defaults and adjust slightly between Pie and Donut mode.
Hover interaction expands the hovered slice outward and shows a tooltip: the slice's dot, its label and value (valueFormat), and its share under them (percentFormat). For other content, write your own with the tooltip's row classes (Custom tooltip):
const d3 = RareCharts.d3;
new RareCharts.Donut('#chart', {
tooltipFormat: ({ label, value, percent, color }) => `
<div class="rc-tooltip-row">
<span class="rc-tooltip-swatch rc-tooltip-swatch--dot" style="--rc-swatch-color:${color}"></span>
<span class="rc-tooltip-label">${label}</span>
<span class="rc-tooltip-value rc-num">$${d3.format(',.0f')(value)}K</span>
<span class="rc-tooltip-note">${d3.format('.1%')(percent)} of revenue</span>
</div>
`,
}).setData(segments);
Circular charts options
Common options shared by all chart types (title, subtitle, source, note, controls, theme) are documented on the Settings page.
| Option | Default | Description |
|---|---|---|
Donut / Pie |
||
height |
280 |
Chart height px |
innerRadius |
0.58 (donut) / 0 (pie) |
Hole size as fraction of outer radius; 0 = Pie |
padAngle |
0.018 (donut) / 0.008 (pie) |
Gap between slices (radians) |
cornerRadius |
3 (donut) / 1 (pie) |
Rounded slice corners px |
showLabels |
false |
Show outer leader-line labels |
labelContent |
'both' |
'both' / 'label' / 'percent' |
labelMinPct |
0.04 |
Hide label when slice < this fraction |
legendPosition |
— | 'right' to place legend in vertical aside |
showCenter |
true (donut) / false (pie) |
Show center text hole |
centerText |
formatted total | String or function(data, info) => string — data: the drawn items, info: { label, value }, the center label and the total. Flat data only — in drill-down the center shows the focused node’s value through valueFormat |
centerLabel |
'Total' |
Secondary line below center text; in drill-down, the levels below the root show the focused node’s label |
valueFormat |
d3.format(',') (e.g. 1,234.5678) |
function(value, info) => string — center total (in drill-down, the focused node’s value) and default tooltip value; info is the slice’s { label, value, percent, color }, or { label, value } for the center |
percentFormat |
.1% |
function(pct, info) => string — outer-label and tooltip percents; info is the slice’s { label, value, percent, color } |
animate |
true |
Animate on first render |
duration |
650 |
Animation duration ms |
ease |
'cubicOut' |
'cubicOut' / 'cubicInOut' / 'linear' |
tooltipFormat |
built-in | function({label, value, percent, color}) => html — the role fields themselves (formatter arguments) |
showRemainder |
false |
Drill-down mode: draw a muted slice for each node’s undisclosed remainder (value − Σ children) |
remainderLabel |
'Other' |
Drill-down mode: fallback label for a surfaced remainder |
strict |
false |
Drill-down mode: throw when a node’s children exceed its stated value (default: warn, leave the negative remainder undrawn) |
onDrill |
— | Drill-down mode: function({ node, path, depth, event }) => void after each change of the level shown, by a click, a key or a drill method (event is then null); not on setData |
Gauge |
||
height |
220 |
Chart height px |
min |
0 |
Minimum value. setData({ value, min }) overrides it for that call only |
max |
100 |
Maximum value. setData({ value, max }) overrides it for that call only |
startAngle |
-¾π |
Arc start (radians, clockwise from top) |
endAngle |
+¾π |
Arc end (270° sweep by default) |
thickness |
0.18 |
Ring thickness as fraction of outer radius |
cornerRadius |
6 |
Arc end rounding px |
needle |
false |
Speedometer pointer pivoting at the dial center; the center readout moves below the hub |
needleColor |
theme text | Needle and hub color |
color |
theme.accent |
Fill arc color |
trackColor |
theme.grid |
Background arc color |
showCenter |
true |
Show center text |
centerText |
share of the range, .0% (e.g. 63%) |
String or function(value, max, min, info) => string; info is { value, max, min, percent, color }, after the arguments it always had |
centerLabel |
— | Secondary line below center text |
animate |
true |
Animate fill on first render |
duration |
650 |
Animation duration ms |
ease |
'cubicOut' |
'cubicOut' / 'cubicInOut' / 'linear' |
tooltipFormat |
built-in | function({value, max, min, percent, color}) => html — color is the fill arc’s (formatter arguments) |