Circular Charts

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.

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)) + 'K',
  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);

Pie

A pie is a donut with innerRadius: 0. The class name is Donut — Pie is an alias. Same API, same options, same behavior.

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.

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?"

setData() accepts a plain number, or an object to override max and min per render:

// 73 out of 100 (default max)
new RareCharts.Gauge('#chart', {
  centerLabel: 'Complete',
}).setData(73);

// 50 achieved out of 80 plan — fills to 62.5%
new RareCharts.Gauge('#chart', {
  max:         80,
  color:       '#00c97a',
  centerText:  (value, max) => `${value}/${max}`,
  centerLabel: 'Achieved',
}).setData(50);

// Override max at render time
gauge.setData({ value: 50, max: 80 });

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
});

Data format

All three types use the same segment data structure:

[
  { 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.

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. Tooltip content is fully customizable:

tooltipFormat: ({ label, value, percent, color }) => `
  <div style="color:${color}">${label}</div>
  <div>${d3.format(',.0f')(value)}</div>
  <div style="color:#888">${d3.format('.1%')(percent)}</div>
`

Circular charts options