Gauge (Rings) API

Concentric rings, outer to inner, each sweeping value / max of a full circle over a background track - see the Gauge demo.

Import

Web Component

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

Vanilla JS

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

const chart = mountGaugeChart(el, props);

Props

Prop	Type	Default	Description
dataSet*	GaugeRingDatum[]	-	Rings, OUTER to INNER; each sweeps value/max of the circle over a track
title	string	-	Optional chart title rendered above the plot
max	number	100	Value corresponding to a full 360° sweep (default 100).
ringThickness	number	18	Ring stroke thickness in px (default 18).
ringGap	number	2	Gap between adjacent rings in px (default 2).
outerRadius	number	null	Outermost ring's outer edge radius in px; default fills the plot box.
startAngle	number	0	Arc start angle in degrees, 0 = 12 o'clock, positive clockwise (default 0).
roundedCaps	boolean	false	Round the arc ends (default false = square caps).
ringOpacity	number | number[]	1	Arc opacity per ring, outer→inner; a single number applies to every ring (default 1).
trackColor	string | string[]	"#00000014"	Track colour(s) behind the arcs, outer→inner; per-ring `trackColor` wins (default "#00000014").
trackOpacity	number | number[]	1	Track opacity per ring, outer→inner (default 1).
defaultActive	number | "inner" | "outer" | null	-	The ring active when nothing is hovered: a dataSet index, "inner"/"outer", or null for none (default "inner").
activeStyle	GaugeActiveStyle	{}	Emphasis applied to the active ring (default { opacity: 1 }).
showCenterLabel	boolean	true	Draw the built-in centre label: active ring's name + formatted value (default true). Turn off to render your own centre overlay (drive it via onHighlightItem).
centerContent	(ring: GaugeRingContext | null) => string	-	Custom centre HTML for the active ring (sanitized before insertion); wins over the default label+value markup. Receives null when no ring is active.
valueFormatter	(v: number) => string	-	Formats a ring value for the centre label and tooltips (default `${v}%`).
noValueLabel	string	-	Centre value text for an active ring with no data (default "n/a").
fontFamily	string	-	Font family for the title/centre label; sets the --michi-vz-font-family CSS var
isLoading	boolean	-	Show the loading overlay and skip the no-data check
isNodata	boolean | ((dataSet: GaugeRingDatum[] | null | undefined) => boolean)	-	No-data override: boolean, or a predicate on dataSet; default = empty dataSet (rings whose value is null still RENDER, as empty tracks).
noDataLabel	string	-	Text for the vanilla default no-data overlay (ignored when suppressed).
suppressDefaultOverlay	boolean	-	A framework wrapper sets this to render its OWN loading/no-data node instead.
tooltipFormatter	(ring: GaugeRingContext) => string	-	Opt-in hover tooltip HTML for a ring (sanitized). Default: no tooltip - the centre label is the built-in readout.
onHighlightItem	(labels: string[]) => void	-	Called with the hovered ring's label (empty array on leave)

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	300	Chart width in pixels
height	number	300	Chart height in pixels
margin	Margin	{ top: p.title ? 36 : 8, 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()

mountGaugeChart(el, props).getContext() returns a renderer-agnostic GaugeChartContext: the max scale, the rings (label / value / fraction / index, outer to inner), summary stats (ring count, largest ring), a deterministic natural-language summary, and an a11y table. See LLM context.

Source

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