Vertical Stack Bar API

Show what each category is built from, segment by segment, with missing parts flagged instead of dropped - see the Vertical Stack Bar demo.

Import

Web Component

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

Vanilla JS

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

const chart = mountVerticalStackBarChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years" (cumulative): the marks draw UP TO the active period and extend as the timeline steps; `interpolate` sweeps smoothly between years, `false` jump-cuts. Headless controller via `chart.timeline()` plus the built-in play button + scrubber. Off by default; wins over `progressiveDraw` when both are set.
progressiveDraw	boolean | ProgressiveDrawConfig	-	Opt-in reveal animation: wipes the marks in left to right on mount (a clip reveal; axes and titles stay put). `true` uses defaults (1200 ms, easeInOutCubic); a config tunes durationMs, easing, autoplay, and replayOnUpdate (`tipLabel` is LineChart-only and ignored here). Off by default; respects prefers-reduced-motion (renders fully drawn instantly) and `replay()` re-runs it.
dataSet*	VerticalStackBarDataSet[]	-	Array of grouped series; each entry contributes its own bar slot per date and stacks its segment keys vertically
keys	string[]	-	Explicit stack order; present keys first (in this order), natural keys appended.
keysOrder	"topToBottom" | "bottomToTop"	"topToBottom"	Where keys[0] sits in the stack: "topToBottom" (default) puts keys[0] at the top, "bottomToTop" anchors keys[0] at the bottom
layout	"vertical" | "horizontal"	"vertical"	Bar orientation. "vertical" (default): columns over a band x-axis - the classic chart, unchanged. "horizontal": rows over a band y-axis with values growing rightward; long category labels render via the shared HTML y-band labels (ellipsized, hoverable). In horizontal mode `keysOrder: "topToBottom"` puts keys[0] nearest the axis (leftmost segment); series-abbreviation labels, `xAxisMode`, and `timeline` apply to the vertical layout only. The category axis keeps the `xAxis*` props and the value axis the `yAxis*` props in BOTH orientations (the "inverted axes" convention), so flipping layout is one prop.
title	string	-	Optional chart title rendered above the plot
xAxisLabelPadding	number	-	Min gap (px) a horizontal x-axis label needs before it tilts -45°. Raise it to give crowded date labels more breathing room (they rotate sooner instead of sitting flush). Default 8 (legacy parity).
xAxisMode	"auto" | "horizontal"	-	"auto" (default) tilts crowded date labels -45°; "horizontal" keeps them flat (thinning instead), so no rotated-label bottom margin is reserved.
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	string[]	-	Explicit ordered list of date band categories; overrides the auto-collected, sorted set of dates from the data
yAxisDomain	[number, number]	-	Fix the y-axis range as [min, max] instead of deriving it from the data
minBarWidth	number	5	Minimum width in px for each bar slot, floored when bands get narrow (default 5)
minBarHeight	number	15	Minimum height in px for a non-zero segment so thin values stay visible (default 15)
minBarHeightZero	number	0	Height in px drawn for an explicit zero-value segment (default 0, i.e. nothing)
missingDataMarker	{ height: number }	-	Opt-in thin stub on the zero line for explicitly-missing (null/NaN) owned keys.
filter	{ limit: number; sortingDir: "asc" | "desc"; date?: string }	-	Keep only the top-N dates ranked by grand total across all series and keys: limit caps the count, sortingDir picks highest (desc) or lowest (asc), optional date is the reference date; chronological order is preserved in output
isLoading	boolean	-	Show the loading overlay and skip the no-data check.
isNodata	boolean | ((dataSet: VerticalStackBarDataSet[] | null | undefined) => boolean)	-	No-data override: boolean or predicate; default = empty / all-empty-series.
noDataLabel	string	-	Text for the vanilla default no-data overlay.
suppressDefaultOverlay	boolean	-	A framework wrapper sets this to render its OWN loading/no-data node.
fontFamily	string	-	Font family for axis/label text (SVG + canvas) via --michi-vz-font-family.
yTicks	number	-	Number of y-axis ticks (default 10).
showGridLines	boolean	-	Draw horizontal dashed y grid lines (default true).
highlightZeroLine	boolean	-	Emphasise the y=0 line with a solid stroke (default true).
tooltipFormatter	(d: StackTooltipData) => 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
onLegendDataChange	(legendData: StackLegendItem[]) => void	-	Called with the computed legend items (label, color, order, disabled, dataLabelSafe) whenever the legend changes

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: 100, left: 60 }	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()

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

Source

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