Pie chart

Sand pours into a ring of annular sectors, then a solid slice fill + border resolves on top, the same particle→solid crossfade every visual shares. Set innerRadius above 0 and a pie becomes a donut. Unlike the other charts a pie shows one series at a time — a slider (styled from axes.x) picks which, and switching series morphs the wedges to the new values.

Constructor

new PieChart(host: HTMLElement, config: PieChartConfig)

Mounts a canvas into host and boots the best available backend (WebGPU → Canvas2D). Only data is required.

Config — top level

Mirrors the bar chart's config surface for the shared blocks; the pie-specific additions are the geometry knobs, seriesIndex/maxSlices/maxSeries/slider, and slices (the bar chart's bars, renamed).

grain — grain appearance

animation — timing

Pie geometry — top-level properties

Series selection & slider

A pie shows exactly one series at a time. The slider — which replaces the bar/line/scatter X axis, and takes its tick styling from the same axes.x block — lets the viewer pick which; dragging it (or calling setSeriesIndex) morphs the wedges to the new series' values. It auto-hides when there is only one series.

slider — SliderConfig

slices — solid fill + border PieStyleConfig

Off by default; a config without slices renders as pure sand. Fill and border always use the slice's color — only opacity and stroke width are configurable (mirrors the bar chart's bars, minus the per-side flags — a wedge outline has no sides to pick).

slices.fill

slices.border

slices.reveal — particle→solid crossfade

Same shape as the bar chart's bars.reveal: start, duration, ease, grainsTo.

Shared blocks

interaction.hover, interaction.dim, legend, currentValue and fps take the same shape the bar chart uses. Full property tables: interaction.hover · interaction.dim · legend · currentValue · fps. axes.x is the same AxisConfig shape but styles the slider, not a drawn axis; axes.y is ignored (a pie has no Y axis).

Methods

Events

hover carries { slice: SliceMeta | null } (null on pointer-leave).

// SliceMeta — metadata for one drawn slice
{
  sliceId: number;
  xValue: Scalar;          // the slice's category
  seriesKey: Scalar | undefined;
  seriesIndex: number;
  value: number;           // raw y
  fraction: number;        // share of the series total, 0..1
  a0: number; a1: number;      // start/end angle, radians clockwise from 12 o'clock
  rInner: number; rOuter: number;  // layout-space radii (rInner 0 for a pie)
  color: RGBA;
}

seriesChange fires whenever the slider selection changes — from a drag or a setSeriesIndex() call:

// SeriesChangePayload
{
  index: number;
  key: Scalar | undefined;
}

seriesFocus carries { index: number | null } — the isolated slice index (see the note under Shared blocks).

Examples

Donut with solid slices

new PieChart(el, {
  data,   // one series: points are the slice categories
  innerRadius: 0.6,
  padAngle: 1.5,
  slices: {
    fill: { opacity: 0.9 },
    border: { show: true, width: 1.5 },
    reveal: { start: 'afterPour', duration: 600, grainsTo: 0.1 },
  },
});

Multiple series — slider morphs between them

new PieChart(el, {
  data,   // DataSet: points grouped by z into several series ('2024', '2025', ...)
  axes: { x: { tickFormat: (v) => `FY ${v}` } },
  slider: { position: 'bottom' },
  animation: { morphDuration: 700 },
});

Legend and current-value readout

new PieChart(el, {
  data,
  legend: { show: true, position: 'right' },
  currentValue: {
    show: true,
    format: (slice) => `${slice.xValue}: ${(slice.fraction * 100).toFixed(1)}%`,
  },
});

Live data — update, add, remove

// Replace the dataset; slices morph to the new shares:
chart.update({ points: [{ x: 'EU', y: 180 }, { x: 'US', y: 140 }, { x: 'APAC', y: 90 }] });

// Append a slice; it opens and its grains pour in:
chart.add({ x: 'LATAM', y: 30 });

// Remove by {x} match or by index:
chart.remove([{ x: 'APAC' }]);

Reacting to the slider

chart.on('seriesChange', ({ index, key }) => {
  heading.textContent = `Showing: ${key}`;
});

// Drive it from code — same morph, same event, as dragging the slider:
nextButton.addEventListener('click', () => {
  chart.setSeriesIndex(chart.getSeriesIndex() + 1);
});