---
id: "packages/active-charts/all-exports/bar-chart"
title: "BarChart"
description: "BarChart, BarChartProps, BarChartSeriesConfig: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/bar-chart"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:bar-chart"
---

# BarChart

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## `BarChart`

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `TDatum[]` | yes | Flat array of row objects keyed by field name. |
| `height` | `number` | yes | Container height in pixels. Width is always responsive. |
| `xKey` | `Extract<keyof TDatum, string> \| XKeyFor<TDatum>` | yes |  |
| `accessibility` | `AccessibilityOptions` | no | Accessibility configuration — ARIA label/description, screen-reader data table, live-region announcements. Merged with ChartDefaults. |
| `animation` | `FeatureOption<Omit<AnimationOptions, "replay">>` | no | How the chart moves: a profile and semantic classes. `false` turns every interpolation off. See {@link AnimationOptions}. |
| `annotations` | `AnnotationOptions[]` | no | Point annotations: a label with an optional connector and marker at a data coordinate, `xValue` on the x axis and `yValue` on the value axis. The contract of `<Chart>`'s `options.annotations` (BC1). |
| `className` | `string` | no | Optional className applied to the outer container. |
| `colors` | `string[]` | no | Categorical palette for this chart only: replaces the host palette (`--chart-1` … `--chart-10`) in the chart's colour assignment, and nothing else. It is a data encoding, not a theme: surfaces, text, grid and semantic roles keep coming from the CSS token contract, and a series, datum or annotation that sets its own colour keeps it. Any CSS colour string (a public token reference such as `var(--chart-3)`, hex, oklch). |
| `contextMenu` | `FeatureOption<ChartContextMenuOptions<CartesianPoint<TDatum>, "copy" \| "export" \| "series" \| "zoom">>` | no | The context menu. Opened on a mark, the host's builder receives a typed {@link CartesianPoint} as `context.target.element` (the point the tooltip names, or the focused point); on empty plot area the target is the chart, on a legend entry the entry. Its own groups are copy, zoom, series and export; a Cartesian chart has no replay. |
| `cornerRadius` | `number` | no | Radius of each bar's value end. Default: 3, clamped to a quarter of the bar's width. |
| `crosshairs` | `boolean \| CrosshairOptions` | no | Enable crosshairs. Default: `false` for bar charts. |
| `crossLines` | `CrossLineOptions[]` | no | Cross lines (reference lines/bands). |
| `dataGrouping` | `boolean \| DataGroupingOptions` | no | Time-based data grouping — aggregates dense time-series into calendar-aligned buckets. Engine default approximation for bar series is `'sum'`. Categorical bar charts typically don't need grouping; leave unset. |
| `defaultSelectedItems` | `readonly ChartItemRef[]` | no | The initial selection of an uncontrolled chart. |
| `dir` | `"ltr" \| "rtl"` | no | The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under `<body>`.  Left out, the chart inherits the direction of the page around it (the nearest `dir` attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from `locale`, and it never reverses an axis or reorders data: `reversed` stays an explicit axis choice. Under `rtl` the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction. |
| `events` | `(ChartEvents & ChartSelectionEvents<TDatum, ChartSeriesItem<TDatum>>)` | no | Every event callback in one prop, selection events included. |
| `grouped` | `boolean` | no | Grouped bars (multiple series side-by-side). Default: true when multiple series. |
| `horizontal` | `boolean` | no | Horizontal bars. |
| `label` | `BarLabelOptions` | no | Value labels for every series; a series' own `label` replaces it for that series (T9). See {@link BarLabelOptions}. |
| `legend` | `boolean \| LegendOptions` | no | Enable legend. Default: `false`. |
| `legendLink` | `ChartLegendLink` | no | Connects the chart's legend to `useChartLegend()`, for a legend the host renders itself. Give one link to one chart. |
| `locale` | `ValuePresentation` | no | Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object (`{languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}`) carrying language and notation independently. `dateShape` is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central `@workspace/active-format`; the package never resolves tenant or application settings itself. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no `'en'` fallback, active-format D14). Object inputs must be referentially stable across renders. |
| `maxWidth` | `number` | no | The widest one bar draws, in CSS px; where there is room every bar draws exactly this wide (CF1). Default: Active's column cap. See `BarSizingOptions.maxWidth`. |
| `name` | `string` | no | Name for the single series. |
| `navigator` | `boolean \| NavigatorOptions` | no | Enable navigator mini-chart with brush. Default: `false`. |
| `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished.  Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. |
| `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. |
| `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). |
| `onItemActivate` | `((item: ChartSeriesItem<TDatum>, source: ChartInteractionSource) => void)` | no | Fired when the reader activates an item: a click or tap on it, or `Enter` on the focused item (`Shift+Enter` on a sankey, whose `Enter` moves between nodes and links). With a handler, `Enter` activates instead of opening the context menu (`Shift+F10` and the context-menu key still open it). |
| `onLegendChange` | `((change: ChartLegendChange) => void)` | no | Fired once for every legend change the chart applies: a hide, a show, an isolation or a show-all, from the built-in legend (click, key, double click, double tap), its menu, or `useChartLegend()`. The change names the entry and its target by identity and lists every hidden target after it. A refused action (the last visible target, `legend.interactive: false`) changes nothing and reports nothing. |
| `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests.  Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness.  A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance).  **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. |
| `onSelectionChange` | `((selection: ChartItemRef[], change: ChartSelectionChange<TDatum, ChartSeriesItem<TDatum>>) => void)` | no | Fired when the reader changes the selection (pointer, touch or keyboard), and when an uncontrolled selection drops items the data no longer contains. `selection` is the complete selection the change makes; it keeps every reference the selection held, of whatever form. On a controlled chart it is a proposal (`change.requested: true`), computed from the current `selectedItems` and never from an earlier proposal; the host applies it, changes it or ignores it. |
| `onZoomChange` | `((startFraction: number, endFraction: number, yStartFraction?: number, yEndFraction?: number) => void)` | no | Fired when the zoom range changes (after animation completes). Fractions [0..1]. Y params are only provided when Y-zoom is active. Cartesian charts only. |
| `ref` | `Ref<ChartHandle>` | no | Imperative handle — see {@link ChartHandle}. Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `selectedItems` | `readonly ChartItemRef[]` | no | The selection, controlled by the host. The chart draws, announces and lists the items it resolves to and never changes it; the host updates it from `onSelectionChange`. A request the host applies is announced when the host passes it back; one it ignores is never announced. A reference to an item that is hidden, zoomed or drilled out of view, or not in the data stays in the host's selection and is not shown as selected. |
| `selection` | `FeatureOption<ChartSelectionOptions>` | no | Item selection. `true` = single selection keyed by the default key. |
| `series` | `BarChartSeriesConfig[]` | no | Multiple series configuration. Mutually exclusive with `yKey`. |
| `stacked` | `boolean` | no | Stacked bars. |
| `stackedPercentage` | `boolean` | no | Percentage stacking (W9). Pass RAW values: the chart draws each value as its share of the visible members of its stack at that row, in percentage points, and restacks to 100 % when a series is hidden. Mixed signs keep their direction: a value's share is its magnitude over the sum of magnitudes, positives above zero and negatives below. Axis, tooltip, table and announcement read percentages; CSV and copy as table export the raw values. Implies stacking; `grouped: true` is ignored with a development warning. |
| `stackTotal` | `StackTotalOptions` | no | One total label per stack and category (BC-S1, the `<Chart>` series `stackTotal`): the net sum of the stack's visible members, beyond the end its sign points to; each stack group has its own. Not drawn on a percentage stack (it always makes 100 %). Present means on, unless `enabled: false`; `formatter` wins over the value semantics. |
| `sync` | `boolean \| ChartSyncOptions` | no | Synchronize with other charts in a SyncGroup. Default: `false`. |
| `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). |
| `tooltip` | `FeatureOption<TooltipOptions>` | no | Tooltip configuration. `true` = defaults, `false` = disabled, object = explicit. |
| `width` | `number` | no | Optional fixed width in pixels. Default: fill container. |
| `widthRatio` | `number` | no | Share of the category step a bar may occupy, 0.1 … 1 (CF1). Default: Active's band. See `BarSizingOptions.widthRatio`. |
| `xAxis` | `"category" \| NumericXAxis<string> \| TemporalXAxis<string, TemporalAxisType> \| (Omit<AxisConfig, "formatter" \| "temporalSemantic" \| "type"> & { formatter?: AxisFormatter<string> \| undefined; } & { type?: "category"; temporalSemantic?: never; })` | no |  |
| `yAxis` | `AxisConfig` | no | Y-axis configuration. |
| `yKey` | `string` | no | Y-axis field name (single series). Mutually exclusive with `series`. |
| `zoom` | `boolean \| ZoomOptions` | no | Enable zoom & pan. Default: `false`. |

## Types

**BarChartProps**

```ts
type BarChartProps<TDatum extends ChartDatum = ChartDatum> =
  BarChartBaseProps<TDatum> &
    BarOrientationProps &
    CartesianXKeyCategoryDefault<TDatum>;
```

**BarChartSeriesConfig**

```ts
interface BarChartSeriesConfig {
  id?: string;
  yKey: string;
  name?: string;
  fill?: string;
  stroke?: string;
  paint?: DatumPaintResolver<DatumFill>;
  cornerRadius?: number;
  yAxisId?: string;
  errorBars?: ErrorBarOptions;
  stackGroup?: string;
  label?: BarLabelOptions;
  visible?: boolean;
  showInLegend?: boolean;
}
```