Comparable Bar API

Two values per label, based vs compared, so before/after shifts read at a glance - see the Comparable Bar demo.

Import

Web Component

import "@michi-vz/wc/comparable-horizontal-bar-chart";
// <michi-vz-comparable-horizontal-bar-chart> is now defined

Vanilla JS

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

const chart = mountComparableHorizontalBarChart(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*	ComparableBarDataPoint[]	-	Array of horizontal-bar rows; each renders two overlaid sub-bars (valueBased behind, valueCompared in front) for one label
title	string	-	Optional chart title rendered above the plot
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
xAxisDomain	[number, number]	-	Fix the x-axis range instead of deriving it from the data
ticks	number	5	Approximate number of axis ticks to generate
tickHtmlWidth	number	100	Width in px reserved for each y-axis (label) tick's HTML (default 100)
colorsBasedMapping	Record<string, string>	-	Optional label -> colour map for the value-based sub-bar ONLY (falls back to the row colour). Pair an opaque light tint here with valueBasedOpacity 1 to make before vs after unmistakable in both themes (legacy michi-vz parity).
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.
valueBasedOpacity	number	0.45	Fill opacity of the two sub-bars (historical look: 0.45 / 0.9).
valueComparedOpacity	number	0.9	Fill opacity of the front valueCompared sub-bar (default 0.9)
xAxisPredefinedDomain	number[]	-	Legacy alias for xAxisDomain (consumers pass [min,max]); wins over xAxisDomain when length===2
patternsMapping	Record<string, string>	-	Per-label image source (data-URI, e.g. createHatchPattern) used to FILL the value-based sub-bar - the canvas tiles it via ctx.createPattern, an SVG renderer via <pattern>/<image>
showZeroLineForXAxis	boolean	false	Draw a solid vertical line at x=0 on the value axis (diverging charts)
showGrid	boolean	false	Draw vertical gridlines on the value axis (default false, legacy parity)
hideTickLabels	boolean	false	Hide the y-axis category labels (consumers control them via the legend column)
minBarWidth	number	5	Floor for a sub-bar's pixel width so near-zero values stay visible (default 5)
padding	{ top: number; right: number; bottom: number; left: number }	ZERO_PADDING	Extra plot-area inset (px); padding.left opens a left column for the y-axis label chips without moving the labels themselves (which stay anchored to margin.left)
horizontalTickPosition	{ x: number; y: number }	-	Offset (px) applied to the y-axis category labels so they align with the legend column
maxBarHeight	number	-	Cap each bar's thickness (px). When few rows would otherwise balloon the bandwidth, the band range shrinks to yield exactly this thickness and is centred in the plot. No-op for dense charts whose natural bandwidth is already below the cap.
symmetricXDomain	boolean	-	Force a symmetric x-domain [-M, M], M = max(|min|, |max|) of the data, so 0 sits centred and the negative/positive sides mirror (e.g. ± growth %). Wins over xAxisDomain / xAxisPredefinedDomain.
layout	"overlay" | "grouped"	"overlay"	How the two sub-bars (valueBased, valueCompared) share a row's band. "overlay" (default): both draw at the full band thickness, one in front of the other - today's behaviour, byte-identical when this prop is omitted. "grouped": the band splits in half - valueBased occupies the top half, valueCompared the bottom half, with no overlap (legacy sdg-trade BarchartHorizontal look). Everything else (scales, colours, patternsMapping, tooltips, maxBarHeight, symmetricXDomain) is identical between modes.
deltaIndicator	DeltaIndicatorConfig	-	Row-level change indicator (arrow + formatted diff label) comparing valueCompared to valueBased. Omitted, or `{ show: false }`, is a provable no-op (zero geometry, zero `.mv-delta` DOM). See DeltaIndicatorConfig JSDoc for the full decision-logic contract.
isLoading	boolean	-	Loading overlay (stale bars hidden while true)
isNodata	boolean | ((dataSet: ComparableBarDataPoint[] | null | undefined) => boolean)	-	No-data predicate/flag; default = empty dataSet
noDataLabel	string	-	Text for the built-in no-data overlay
suppressDefaultOverlay	boolean	-	Set by a framework wrapper passing its own overlay node - suppresses the default overlay
filter	{ limit: number; criteria: "valueBased" | "valueCompared"; sortingDir: "asc" | "desc"; }	-	Keep only the top-N labels ranked by the chosen field: limit caps the count, criteria selects "valueBased" or "valueCompared", sortingDir picks highest (desc) or lowest (asc)
tooltipFormatter	( d: ComparableBarDataPoint, dataSet?: ComparableBarDataPoint[], type?: "based" | "compared", ) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted). `type` is the hovered sub-bar ("based" | "compared"); `dataSet` is all rows.
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	900	Chart width in pixels
height	number	480	Chart height in pixels
margin	Margin	{ top: 50, right: 50, bottom: 50, left: 120 }	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()

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

Source

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