Gap Chart API

Show the distance between two numbers and let the bar carry the punch - see the Gap Chart demo.

Import

Web Component

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

Vanilla JS

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

const chart = mountGapChart(el, props);

Props

Prop	Type	Default	Description
dataSet*	GapDataItem[]	-	Array of rows, one horizontal value1->value2 gap bar per item
title	string	-	Optional chart title rendered above the plot
colorMode	"label" | "shape"	"label"	Whether marks are colored per row label ("label", default) or per role/shape via shapeColorsMapping ("shape")
shapeColorsMapping	ShapeMapping	-	When colorMode is "shape", the colors for the value1, value2, and gap parts
shapesLabelsMapping	ShapeMapping	-	Optional display labels for the value1/value2/gap roles (e.g. legend captions)
filter	Filter	-	Top-N / sort filter applied to the data before rendering
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`. The user's `filter` still applies within each period.
shapeValue1	"circle" | "square" | "triangle"	"circle"	Marker shape for the value1 endpoint: "circle" (default), "square", or "triangle"
shapeValue2	"circle" | "square" | "triangle"	"circle"	Marker shape for the value2 endpoint: "circle" (default), "square", or "triangle"
xAxisDataType	"date_annual" | "date_monthly" | "number"	"number"	How x values are parsed and formatted: yearly dates, monthly dates, or plain numbers
xAxisDomain	[number, number]	-	Fix the value-axis range as [min, max] instead of the derived zero-baseline domain (e.g. zoom a life-expectancy story into its 35-90 band)
interactiveRowLabels	boolean	false	Make the row labels interactive: hovering or focusing a label draws a leader line to its row's marks, highlights the row, and shows its tooltip; clicking pins the tooltip. Labels become keyboard-focusable. Default false.
xAxisFormat	(d: number | string) => string	-	Formats an x tick value into its display label
yAxisFormat	(d: number | string) => string	-	Formats a y tick value into its display label
ticks	number	5	Approximate number of axis ticks to generate
tickValues	Array<number | Date>	-	Explicit tick values, overriding the generated ones
enableExplicitTickValues	boolean	-	When false, ignore `tickValues` for tick placement and GapChart's mark-scale domain, letting the chart use its data-derived domain and generated ticks.
tickHtmlWidth	number	100	Width in px of the HTML y-axis label box, which ellipsizes longer labels (default 100)
squareRadius	number	2	Corner radius in px for square markers (default 2)
showZeroLineForXAxis	boolean	false	Draw a solid vertical line at x=0 on the value axis (diverging charts). Default false.
maxBarHeight	number	-	Cap each row's thickness (px). When few rows would otherwise balloon the bandwidth (a scaleBand stretched over the full plot height), the band range shrinks to yield exactly this thickness and is centred in the plot (symmetric whitespace), so a 1-2 row chart reads tidily instead of a single row floating mid-plot. No-op for dense charts whose natural bandwidth is already below the cap. Mirrors ComparableBarChart's `maxBarHeight`.
showLegend	boolean	-	Whether to render a legend
legendAlign	"left" | "center" | "right"	-	Horizontal alignment of the legend: "left", "center", or "right"
tooltipFormatter	(d: GapDataItem) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
isLoading	boolean	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
isNodata	boolean | ((dataSet: GapDataItem[] | null | undefined) => boolean)	-	No-data override: boolean, or a predicate on the data; default = empty data.
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.
onHighlightItem	(item: GapDataItem | null) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	1000	Chart width in pixels
height	number	500	Chart height in pixels
margin	Margin	{ top: 50, right: 150, bottom: 100, left: 150 }	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()

mountGapChart(el, props).getContext() returns a renderer-agnostic GapChartContext (structured stats + a deterministic natural-language summary + an a11y table). See LLM context.

Source

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