Charts

Bar Chart

Compare values across categories with vertical or horizontal bars.

Charts / Bar Chart

Preact nativeGrouped & stackedTyped fill accessorsReference areas

Overview

Bar charts compare categorical values along a band or point scale. Kamod keeps legend, tooltip, and reference colors on stable series tokens while per-bar fill accessors can reflect each datum.

import { BarChart } from "@kamod-ch/charts/bar";

Static bundle: Import from @kamod-ch/charts/bar for charts without the motion runtime.
Animation: Motion helpers live behind @kamod-ch/charts/motion when you need enter or update transitions on bar geometry.

API notes

Typed BarChart props — no option objects and no React-only patterns.

color vs fill: color is the stable series token for legend and tooltip swatches. fill (string or accessor) paints individual bars and may vary per datum without changing legend semantics.
Signed values: Do not rely on bar color alone for positive versus negative meaning. Pair fill with valueLabels, tooltips, or explicit description text so the sign is readable without hue.
grouped vs stacked: grouped (default) places series side-by-side within each category band. stacked builds cumulative segments; tooltips and labels still report raw series values, not stack totals.
maxBarSize: Caps bar width on vertical charts and bar height on horizontal charts. Bars stay centered inside the category band; hit-testing and motion use the same limited geometry.
valueLabels: true enables auto placement (outside for grouped, center/outside for stacks). Pass BarValueLabelOptions for position, format, and per-series overrides. On vertical charts, outside sits above positive bars; on horizontal charts, outside extends past the bar tip.
referenceAreas: Semantic x1/x2 always refer to categories and y1/y2 to values — BarChart maps them to the visible axes when orientation="horizontal". Areas render behind grid and bars and do not affect domains or hit-testing.
BarDatumContext: Fill and label accessors receive datum, value, stack bounds, orientation, and an active flag when the bar is keyboard- or pointer-selected.
Theme tokens: Prefer var(--chart-1) … var(--chart-4) and var(--chart-reference-area) so fills adapt in light and dark themes.

Gallery

Eight functional patterns covering sizing, orientation, stacking, signed fills, value labels, and reference bands. Each preview uses Kamod’s real BarChart API — no copied option objects.

Sized vertical bars

Cap bar width with maxBarSize and soften corners with radius. Bars stay centered inside each category band.

maxBarSizeradiusresponsive

Drag the container edge — the chart reflows while keeping the 32px bar cap.

Horizontal bars with long labels

Categories map to the Y axis on horizontal charts — useful when labels need more room than a vertical band allows.

orientationhorizontal

Grouped series with legend

Related metrics sit side-by-side. The HTML legend toggles visibility without moving keyboard focus off the chart surface.

groupedshowLegendonBarClick

Select a bar with pointer or keyboard (Enter).

Stacked composition

Stack series to show part-to-whole relationships. Tooltip rows still expose each series’ raw value.

stackedtooltip

Signed values with typed fill

Use a BarFill accessor for datum-driven color, but pair it with labels or tooltips so sign is not conveyed by hue alone.

fillvalueLabelsa11y

Formatted value labels

Pass BarValueLabelOptions for placement, formatting, and styling. Returning null from format suppresses a label.

valueLabelsformat

Compact stacked chart

A shorter frame with stacked bars, nearest tooltips, and legend toggles — suited to dense dashboard tiles.

stackedtooltipshowLegend

Carrier week with MTD band

Highlight a category interval with referenceAreas. x1/x2 always refer to categories even when the chart is horizontal.

referenceAreasgrouped

Bar chart accessibility

Set title and description on every production chart — they render into SVG title and desc elements.
Tooltips expose a polite live region for pointer and keyboard updates; bar charts default to nearest mode.
Legend buttons toggle series visibility while the chart surface keeps focus for arrow-key navigation.
For signed or thresholded data, expose the sign or status in labels or tooltips — not color alone.
Reference area labels are decorative (aria-hidden) and never receive tab stops.

Props

BarChart props
Prop	Type	Default	Description
data	readonly TDatum[]	—	Array of row objects rendered by the chart.
xKey	DataAccessor<TDatum, string \| number \| Date \| null \| undefined>	—	Field or accessor for the x axis.
xScale	"linear" \| "time" \| "band" \| "point"	—	Scale kind for the x axis.
height	number	—	Chart height in pixels.
width	number	—	Fixed width. Prefer responsive + initialWidth for fluid layouts.
initialWidth	number	—	SSR / first-paint width before ResizeObserver measures the container.
responsive	boolean	false	Stretch to the parent container width.
title	string	—	Accessible chart title rendered into SVG title.
description	string	—	Accessible description rendered into SVG desc.
showGrid	boolean	—	Show cartesian grid lines.
showLegend	boolean	—	Show an HTML legend with series toggles. Supported on Line, Scatter, Area, and Bar charts.
tooltip	boolean \| CartesianTooltipOptions<TDatum>	—	Enable pointer and keyboard tooltips. `true` uses chart defaults: axis mode for Line and Area, nearest mode for Scatter and Bar. Options may set mode, placement, offset, render, formatValue, and formatLabel. PieChart does not support this prop.
animate	boolean \| ChartAnimateOptions	—	Optional data animation. No-op on static entries unless a MotionConfig from @kamod-ch/charts/motion is present. Defaults to on for charts imported from that subpath. Options: enabled, duration (seconds), easing, preset, reducedMotion.
series	readonly BarSeriesConfig<TDatum>[]	—	One or more bar series. BarSeriesConfig extends the cartesian config with fill and per-series valueLabels.
orientation	"vertical" \| "horizontal"	"vertical"	Bar direction. Vertical maps categories to X and values to Y; horizontal swaps those axes.
stacked	boolean	false	Stack series into cumulative segments per category. Tooltips and value labels still report raw series values.
grouped	boolean	true	Place series side-by-side within each category band when stacked is false. Ignored when stacked is true.
radius	number	0	Corner radius in pixels for bar rectangles.
minBarSize	number	—	Minimum bar thickness along the value axis (width on vertical charts, height on horizontal).
maxBarSize	number	—	Maximum bar thickness along the value axis. Bars stay centered inside the category band; hit-testing and motion share the same capped geometry.
valueLabels	boolean \| BarValueLabelOptions<TDatum>	false	Chart-level value label defaults. true enables auto placement. Series may override with BarSeriesConfig.valueLabels.
referenceLines	readonly CartesianReferenceLine<TDatum>[]	—	Optional x/y threshold lines. On vertical charts, y is a numeric value and x may be a category string for horizontal orientation.
referenceAreas	readonly CartesianReferenceArea<TDatum>[]	—	Category or value highlight bands rendered behind grid and bars. x1/x2 always refer to categories; y1/y2 refer to values regardless of orientation.
onBarClick	(datum, seriesId, index, value) => void	—	Pointer click handler for a bar. Keyboard users activate the focused bar with Enter on the chart surface.

BarSeriesConfig

Fields on each series entry
Prop	Type	Default	Description
key	DataAccessor<TDatum, number \| null \| undefined>	—	Numeric field or accessor for bar length.
id	string	—	Stable series identifier for legend toggles and onBarClick. Defaults from key when omitted.
label	string	—	Human-readable name for legend and tooltip rows.
color	string	—	Stable series color for legend swatches and tooltip accents. Does not change when fill varies per datum.
hidden	boolean	false	Hide the series without removing it from the config (legend can re-enable).
fill	BarFill<TDatum>	—	Per-bar fill: a CSS color string or accessor (context) => string \| undefined. Falls back to color when omitted.
valueLabels	boolean \| BarValueLabelOptions<TDatum>	—	Per-series value label override. Merged over chart-level valueLabels.

BarFill

BarFill type alias
Prop	Type	Default	Description
BarFill	string \| ((context: BarDatumContext<TDatum>) => string \| undefined)	—	Static token such as var(--chart-1) or a function that receives BarDatumContext and returns a fill color.

BarDatumContext

Passed to fill accessors and extended by BarValueLabelContext for valueLabels.format.

BarDatumContext fields
Prop	Type	Default	Description
datum	TDatum	—	The data row for this bar.
index	number	—	Row index in the data array.
value	number	—	Resolved numeric value for this bar.
valueStart	number	—	Stack baseline along the value axis (0 for grouped charts).
valueEnd	number	—	Stack top along the value axis (value when not stacked).
seriesId	string	—	Resolved series id passed to fill and label accessors.
seriesIndex	number	—	Index of the series in the series array.
orientation	"vertical" \| "horizontal"	—	Chart orientation at render time.
stacked	boolean	—	Whether the chart is in stacked mode.
active	boolean	—	True when the bar is pointer- or keyboard-selected.

BarValueLabelOptions

Chart-level via valueLabels or per-series via BarSeriesConfig.valueLabels. Series options override chart defaults.

BarValueLabelOptions fields
Prop	Type	Default	Description
position	"auto" \| "inside" \| "outside" \| "center"	"auto"	Label placement. auto centers inner stack segments and places the outer segment outside. outside sits beyond the bar along the value axis; inside tucks into the bar end; center uses the bar midpoint.
format	(value, context: BarValueLabelContext<TDatum>) => ComponentChildren	—	Custom label content. Return null to suppress a label for that bar. BarValueLabelContext extends BarDatumContext with defaultLabel.
color	string	—	SVG fill color for label text.
class	string	—	Optional class applied to the label text element.
offset	number	4	Pixel gap between the bar edge and an outside or inside label.

referenceAreas entries

CartesianReferenceArea fields used by BarChart
Prop	Type	Default	Description
id	string	—	Optional stable id for the area element.
x1	string \| number \| Date	—	Start category (band scale) for a vertical category band.
x2	string \| number \| Date	—	End category for the band. Same category as x1 highlights one band.
y1	number \| Date \| string	—	Lower value bound when highlighting a value range.
y2	number \| Date \| string	—	Upper value bound for value-range highlights.
label	string	—	Decorative label (aria-hidden). Not a tab stop.
fill	string	—	Fill color. Prefer var(--chart-reference-area) for theme-aware bands.
fillOpacity	number	—	Opacity multiplier for the fill color.

Label placement

Value labels follow the value axis regardless of orientation:

Vertical: outside sits above positive bars and below negative bars; inside tucks into the bar end; center uses the bar midpoint.
Horizontal: outside extends past the bar along X; inside sits inset from the bar tip; center stays at the bar center.
Stacked + auto: inner segments use center; the outermost positive (or negative) segment uses outside so totals are not duplicated.

Orientation and reference geometry

Vertical bars (default) use a categorical X axis and numeric Y axis. Horizontal bars swap those roles — categories align on Y so long labels stay readable.

Reference areas always use semantic coordinates: x1 / x2 refer to category keys and y1 / y2 to numeric values. BarChart maps them to the visible axes when orientation="horizontal".

Reference lines follow the same axis mapping as LineChart: referenceLine.y is a numeric threshold on vertical charts (or a category string on horizontal charts).