Bar Chart

A general-purpose stacked bar chart for categorical datasets, with optional line overlays.

Volume by month

6,450

Usage

import { BarChart, type BarChartSeries } from '@epilot/spark-ui/bar-chart'

function VolumeByMonth() {
  return (
    <BarChart
      data={data}
      series={series}
      getCategory={(datum) => datum.month}
      title="Volume by month"
      yAxisUnit="units"
    />
  )
}

Use BarChart when categories are discrete buckets (hours, days, months) and you control the series config. For the energy-source stack with an animated total, use Energy Bar Graph. For week/month/year home energy with fixed solar/battery/grid series, use Energy History Chart. For continuous time series, use Line Chart.

The chart sizes itself to its container width. Negative series values render below the baseline.

Examples

Highlighting a category

highlightedCategory marks a bucket; showHighlightLine draws a vertical dashed line through it (current hour, selected day, and similar).

Volume by month

6,450

Line overlays

lines draw on top of the bars and appear in the legend so users can toggle them. Each line can use its own y-domain (for example a 0–100% ratio overlay).

Volume by month

6,450

API Reference

`BarChartProps<TDatum>`

Prop	Type	Default	Description
`data`	`TDatum[]`	—	One row per category.
`series`	`BarChartSeries<TDatum>[]`	—	Stacked bar segments. Order is bottom to top.
`lines`	`BarChartLineSeries<TDatum>[]`	—	Optional overlays drawn above the bars and listed in the legend.
`getCategory`	`(datum) => string \| number`	—	X-axis key for each row.
`categories`	`(string \| number)[]`	from `data`	Full ordered x-domain when it differs from the data order.
`categoryTicks`	`(string \| number)[]`	every category	Subset of categories that render an x-axis label (thin dense axes).
`formatCategory`	`(c) => string`	`String(c)`	X-axis tick labels.
`formatTooltipCategory`	`(c) => string`	`formatCategory`	Tooltip header. Use a fuller label when axis ticks are abbreviated.
`highlightedCategory`	`string \| number`	—	Emphasizes one bucket (dimmed peers).
`showHighlightLine`	`boolean`	`false`	Vertical dashed marker through `highlightedCategory`.
`referenceLine`	`{ value, label?, color? }`	—	Horizontal threshold across the plot.
`title`	`string`	—	Section title above the legend.
`yAxisUnit`	`string`	—	Unit drawn once above the y-axis; ticks use the compact shared formatter.
`formatYTick`	`(value: number) => string`	compact ticks	Overrides y-axis tick labels.
`yAxisWidth`	`number`	measured	Fixed y-axis gutter width in px.
`height`	`number`	`220`	Plot height in px.
`renderTotal`	`(value: number, animated: boolean) => ReactNode`	—	Custom total above the chart. `animated` is false while a bar is hovered so totals can snap.
`formatTotal`	`(value: number) => string`	locale number	Default total formatter when `renderTotal` is omitted.
`formatValue`	`(value: number) => string`	`formatTotal`	Per-series tooltip values.
`className`	`string`	—	Merges onto the root.

`BarChartSeries<TDatum>`

Field	Type	Description
`key`	`string`	Stable series id (legend, tooltip, stack key).
`label`	`string`	Legend and tooltip label.
`color`	`string`	CSS color for the bar fill.
`hoverFill`	`string`	Optional fill while that segment is hovered.
`getValue`	`(datum: TDatum) => number`	Value read from each row. Negatives stack below zero.

`BarChartLineSeries<TDatum>`

Field	Type	Description
`key`	`string`	Stable id.
`label`	`string`	Legend and tooltip label.
`color`	`string`	Stroke color.
`getValue`	`(datum) => number \| null`	`null` breaks the line (gap for missing readings).
`domain`	`[number, number]`	Own y-domain. Defaults to the bar scale.
`hiddenByDefault`	`boolean`	Starts hidden; the user can enable it from the legend.
`formatValue`	`(value: number) => string`	Tooltip formatter for this line. Defaults to the chart `formatValue`.
`strokeDasharray`	`string`	Dash pattern for the overlay stroke.

Accessibility

Bars are not individually focusable. Provide a summary or table when values drive a decision.
The legend toggles series with buttons (aria-pressed). Hidden series get a struck-through label and reduced opacity.
Hover tooltips are pointer-only; keep critical totals visible via title / renderTotal.

Bar Chart

Volume by month

Volume by month

Volume by month

On this page