Pie / Donut API

Slices sized by share of a whole, with a donut mode one prop away (innerRadiusRatio) - see the Pie / Donut demo.

Import

Web Component

import "@michi-vz/wc/pie-chart";
// <michi-vz-pie-chart> is now defined

Vanilla JS

import { mountPieChart } from "@michi-vz/core";

const chart = mountPieChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years": snapshots one period at a time over the distinct per-row `date` values, with a headless controller (`chart.timeline()`) plus an optional built-in play button + scrubber. Off by default; requires rows with `date`. Values tween between periods unless `interpolate: false`.
dataSet*	PieDataItem[]	-	Array of slices; each value becomes a wedge sized by its share of the total
title	string	-	Optional chart title rendered above the plot
innerRadiusRatio	number	0	0 = full pie (default); (0,1) = donut hole as a fraction of the outer radius.
padAngle	number	0	Gap between slices in radians (default 0).
cornerRadius	number	0	Corner radius on the arcs in px (default 0).
sortByValue	boolean	true	Sort slices by value descending (default true); false keeps data order.
showLabels	boolean	true	Draw the % label inside each slice when it is large enough (default true).
showLegend	boolean	false	Render a swatch+label legend below the chart (default false).
filter	{ limit: number; sortingDir: "asc" | "desc" }	-	Keep only the top-N slices by value.
valueFormatter	(n: number) => string	-	Formats a numeric value for labels and tooltips
tooltipFormatter	(slice: PieSliceContext) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
onHighlightItem	(labels: string[]) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	600	Chart width in pixels
height	number	420	Chart height in pixels
margin	Margin	{ top: 36, right: 8, bottom: 8, left: 8 }	Inner margins (top/right/bottom/left, in px); default 8 (36 top with a title)
colors	string[]	-	Categorical palette for rings without an explicit colour or colorsMapping entry
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
highlightItems	string[]	-	Labels to emphasise (active styling); others keep their base opacity
disabledItems	string[]	-	Labels to hide entirely (ring + track removed; remaining rings keep their radii order)
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas / WebGPU layer; getContext() is identical either way
locale	string	-	BCP-47 locale used for number formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so arc colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate opacity/arc changes with CSS transitions (SVG renderer; default true)
onColorMappingGenerated	(mapping: Record<string, string>) => void	-	Called with the resolved label -> colour map after the chart assigns colours
onChartDataProcessed	(context: ChartContext) => void	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
onDataWarning	(warnings: DataWarning[]) => void	-	Called with any non-fatal data warnings (out-of-range values, duplicate labels, ...)

Events

The web component dispatches these bubbling CustomEvents (the engine exposes the same via the on* callbacks in the table above):

Event	Detail	Fires when
michi-vz:highlight	string[]	hover highlight changes
michi-vz:colormapping	Record<string, string>	a color mapping is generated
michi-vz:dataprocessed	ChartContext	data is (re)processed
michi-vz:datawarning	DataWarning[]	input warnings are detected

getContext()

mountPieChart(el, props).getContext() returns a renderer-agnostic PieChartContext: the mode ("pie" or "donut"), innerRadiusRatio, the slices (label / value / share / start & end angle), summary stats (slice count, total, largest slice), a deterministic natural-language summary, and an a11y table. See LLM context.

Source

Props are typed as PieChartProps in @michi-vz/core.