# Bar Chart

Bar chart for comparing values: grouped, horizontal, diverging, top-k and highlighted bars, with tooltip, keyboard navigation and a data table.

- Category: Charts
- Page: https://wunderui.com/components/bar-chart
- Tier: Core and Pro

## Install

Bar Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { BarChart, BarChartProps, BarChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { BarChart } from "@wunderui/react/charts"

const data = [
  { month: "Jan", revenue: 32000 },
  { month: "Feb", revenue: 41000 },
  { month: "Mar", revenue: 38000 },
  { month: "Apr", revenue: 47000 },
]

export function RevenueBars() {
  return <BarChart data={data} index="month" series={[{ key: "revenue", label: "Revenue" }]} label="Revenue" />
}
```

Expected result: You should see four columns rising from a zero line, with the months below. Hovering a column lights a band and opens a tooltip.

## When to use

### Use Bar Chart for

- Comparing values across categories
- Two or three series side by side (grouped bars)
- A ranking, as horizontal bars or a top-k list with the rest summed into Others
- Gains and losses around zero, or two sides compared (butterfly)

### Use something else

- [Line Chart](https://wunderui.com/components/line-chart) for a trend over many points in time
- [Stacked Chart](https://wunderui.com/components/stacked-chart) for the parts that make up each total
- [Range Bar Chart](https://wunderui.com/components/range-bar-chart) for a span from a minimum to a maximum per category
- [Distribution Chart](https://wunderui.com/components/distribution-chart) for raw observations that need binning

## Keyboard

The plot is focusable, so the chart works without a pointer.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | Moves to the next or previous category. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one). |
| `Home` or `End` | Jumps to the first or last category. |
| `Shift+ArrowRight` or `Shift+ArrowLeft` | Extends a selected range from the point you started on. A range is only selected when `onSelectedRangeChange` is set. |
| `Escape` | Clears the active point and the selected range. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

On the horizontal variants and the top-k list the categories run top to bottom, so Up and Down walk them instead of Left and Right.

## Behavior

What the chart does on its own and what the page decides.

- **Bar width:** Bar width follows the band (43 percent for a single series). You can cap it and override the corner radius.
- **Variants set the look:** The variant picks the fill (solid, stroke, gradient, dashed, pattern), the shape (lollipop, capsule, track, segmented, tick), the direction and what the bar says (labels, threshold, highlight).
- **Threshold and highlight:** The threshold bar keeps bars at or above the threshold in their colour and turns the others grey. The highlighted bar draws one bar (the last by default) in a highlight colour (blue by default).
- **Top-k:** Top-k keeps the largest categories (6 by default) and adds the rest into one bar, named Others with the count unless you set a label.
- **Legend and layout:** A series switched off in the legend keeps its slot and fades, so the groups do not jump.
- **Texture and ghost trail:** A texture replaces the grid, never adds to it, and only one decorative layer goes on a chart (no texture with a pattern or a glow). The ghost trail draws last period faint behind the current one and morphs with the data.
- **Hero variants:** 3d-bar and square-bar are named hero variants: glass blocks lit from above with their sides turned to the middle of the chart (gradients only, no filter), and bars built from 2 px-spaced squares that keep their true length. Never a default and never in a dense dashboard.
- **New period:** New data morphs: the bars grow or shrink to their new values, and a new number of bars (12 months to 30 days, a new time bucket) is resampled onto the new slots instead of replaying the enter sequence.
- **Legend on small cards:** In a ChartCard under 560 px the legend keeps to one row: the badges that fit, then a +n button that opens the rest.
- **Loading, empty and error:** The chart keeps its size while it loads, is empty or fails, so the card never jumps. Loading shows a skeleton; error adds a Try again button when a retry handler is set.
- **Legend:** A ChartCard shows series as badges. With two or more series each badge switches its series off, the last visible one stays on, and a legend of roles can be made static.
- **Data table:** The chart also renders its data as a table for screen readers, in plot order. A ChartCard can show that table on screen through a toggle that keeps the card height.
- **Size:** The chart fills its container's width; you set the plot height. Text never scales: labels keep their size at every width.

## Motion

The enter sequence and the hover follow the motion tokens of the library.

- **Grow:** Bars grow from the zero line the first time the chart is in view, and again after loading or when new data arrives. You can turn the animation off.
- **Hover:** The muted band behind the active category moves with the pointer or the arrow keys.
- **Reduced motion:** With reduced motion on, the enter sequence is off and the chart appears at once. Tooltip, crosshair and every state still work.

## Anatomy

- `BarChart`: Takes data, an index and series. Bar width follows the band (43 percent for a single series); you can cap it, override the corner radius, or fill bars with a pattern in the series colour.
- `Plot`: The focusable region. Left and Right (Up and Down on horizontal variants) walk the categories, Home and End jump, Shift with an arrow selects a range when a range handler is set.
- `Grid and axes`: Horizontal grid lines and a left value axis for columns. Horizontal variants and the top-k list get vertical grid lines, a bottom value axis and a left category axis sized to the longest label.
- `Bars`: One rounded bar per series and category, growing from the zero line. A negative value hangs below it; a series switched off in the legend keeps its slot and fades, so groups do not jump.
- `Value labels`: Numbers at the bar ends for labelled bars, top-k and butterfly, or anywhere when values are shown. When they all fit they all show; if not, only the hovered or focused category gets one.
- `Threshold line`: The threshold bar has a dashed line with a tag, such as Target 30k. Bars at or above the threshold keep their colour and the others turn grey.
- `Butterfly`: The two-sided butterfly layout: the first series grows left, the second right, with the category name in a column between them.
- `Tracks`: The pale full-height capsule behind each bar of the track bar, showing how far the bar is from the top of the scale.
- `Tooltip`: Hovering or focusing a category lights a muted band behind it and opens the tooltip with one row per visible series. The change chip compares with the previous category.
- `Loading, empty and error`: The skeleton is muted columns (or rows on horizontal variants) shaped like the real data, under the shimmer. Empty and error messages replace the bars; the error offers Try again.
- `Data table and live region`: Every category and series as a screen-reader table, and a live region that announces the active category with all its values.
- `Chart Ghost`

## Best practices

### When to use

- Use BarChart to compare amounts across categories or a few periods. Use StackedChart when the parts of one total matter, and PieChart only for three or four shares of a whole.

### Do

- Pick the orientation from the labels. Long category names such as plan or region names belong on a horizontal variant, where the left axis grows to fit them instead of rotating or cutting text.
- Keep grouped bars to three series. More makes each bar too thin to hover; switch to a horizontal variant or small multiples.
- Add a pattern when the chart is printed or colour alone is not enough: one pattern form per chart (stripes or dots) for every series, which stay apart by their colour. Patterned bars are at least 20 px wide; on narrow charts neighbouring categories are gathered first.
- Annotate with props instead of drawing on top: forecastFrom (striped forecast bars and an Actual / Forecast legend via forecastLegendItems), trendline, events (icon buttons with a tooltip, a counter for several at one index) and range (grey stripes behind the bars).

### Don't

- Don't start the value axis above 0. Bar length is the value, so a cropped baseline exaggerates differences; use LineChart or RangeBarChart when the interesting part is the narrow band.
- Don't sort the top-k chart by hand and then pass every row. Set the top count and let the rest collapse into the Others bar, so the list stays at six or seven rows.

## API reference

### BarChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per category / point. |
| index* | string |  | Field holding the category label (x axis; y axis for horizontal bars). |
| series* | readonly ChartSeries[] |  | The series to draw, in order. |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| aggregate | ChartAggregate \| Readonly<Record<string, ChartAggregate>> |  | Bars on a time axis (`xScale="time"`) that would get thinner than 6 px are gathered into weeks, months, quarters or years (`resolution="auto"`, the default). How a bucket sums up each series: `sum` (default), `mean` or `last` — one for all… |
| animate | boolean |  | Enter sequence (draw, wipe, grow) on scroll into view, after loading and on new data. Default true; off with reduced motion. |
| animationKey | string \| number |  | Change it to play the enter sequence again (e.g. `useChartReload().version`). New `data` replays it by itself. |
| aspectRatio | number |  | Width ÷ height when `height` is not set. Default 2.6. |
| axisFormatter | ChartValueFormatter |  | Value-axis labels; defaults to `valueFormatter`. |
| barWidth | number |  | Maximum bar width (thickness for horizontal bars) in px. |
| categoryAxis | boolean |  | Category-axis labels (default true). |
| categoryFormatter | (label: string) => string |  | Shortens category labels on the axis, e.g. "Mar 12" → "Mar"; tooltip and pill keep the full label. |
| categoryTicks | readonly string[] |  | Only these category labels are shown on the axis (the rest stay hoverable). |
| className | string |  | Extra classes for the root element of the chart. |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| defaultSelectedRange | ChartRange \| null |  | The range that is selected at first, for an uncontrolled chart. |
| description | string |  | Screen-reader summary; generated from the data when omitted. |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| events | readonly ChartEvent[] |  | Event markers: a dotted line over the plot and a round icon button above it; several at one index get a counter badge. |
| forecastFrom | number |  | Index of the first forecast category. From there a dashed divider with a label ("Forecast from Oct"); lines turn dotted and end on a dot, areas fill with stripes, bars are striped with a rim in the series colour. |
| forecastLabel | string |  | Label of the forecast divider. Default "Forecast from <category>" (on small charts "Forecast"). |
| ghost | string \| ChartGhost |  | The previous period as a faint ghost behind one series: a field name, or `{ key, label, series }`. Bars get a faint dashed column behind each bar. The tooltip lists it under its series, the table adds a column; give the legend item `ghost: true` for a faint ring. |
| grid | boolean |  | Grid lines (default true). |
| gridFade | boolean |  | The grid fades out towards both ends (default true). |
| gridIntervals | number |  | Number of equal grid intervals. Default: one per 44 px of plot height, capped by the size class (xs 2, sm 3, md 3, lg 4, xl 5). |
| gridStyle | "solid" \| "dashed" |  | Grid lines are dashed 4 / 4 by default; `solid` draws them through. |
| height | number |  | Fixed height of the plot frame in px. Without it the height follows the width (`aspectRatio`, `minHeight`, `maxHeight`): 220 px on a phone, up to 434 px (the plot of the Figma large card) from about 1130 px wide. |
| hiddenSeries | readonly string[] |  | Series keys that are switched off (legend toggle): drawn faded, dimmed in the tooltip. |
| highlightColor | "indigo" \| "blue" \| "purple" \| "green" \| "orange" \| "pink" \| "yellow" \| "red" \| "grey" | "blue" | `highlighted-bar`: colour of the emphasised bar. Default blue. |
| highlightIndex | number |  | `highlighted-bar`: the emphasised category (default: the last one). |
| includeZero | boolean |  | The value axis starts at 0 (owner rule, default). `false` fits the data (prices, temperatures). |
| label | string |  | Accessible name, e.g. the card title. |
| maxHeight | number |  | Highest height from `aspectRatio`. Default 434. |
| minHeight | number |  | Lowest height from `aspectRatio`. Default 220. |
| negativeColor | "indigo" \| "blue" \| "purple" \| "green" \| "orange" \| "pink" \| "yellow" \| "red" \| "grey" | "red" | `negative-bar`: colour of bars below zero. Default red. |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| onSelectedRangeChange | (range: ChartRange \| null) => void |  | Called when a drag across the plot or Shift with an arrow key changes the range, and with `null` when Escape or a click clears it. |
| othersLabel | string |  | `top-k-with-others`: label of the summed bar. Default "Others (n)". |
| pattern | ChartPattern \| readonly ChartPattern[] |  | Fill the bars with a pattern instead of the variant's fill. One pattern form per chart (owner, Nov 12 2026): every series takes the same form — stripes or dots — and the series stay apart by colour only. A list is still accepted for older… |
| radius | number |  |  |
| range | ChartRangeHighlight |  | A highlighted range of categories with grey stripes behind the marks and an optional label. |
| rangeSelectable | boolean |  | Allow selecting a range by dragging or Shift + arrow keys. On when `onSelectedRangeChange` is set. |
| resolution | "auto" \| "full" |  | `auto` (default): lines and areas draw at most 1.5 points per pixel (LTTB; hover and tooltip keep every point), and bars on a time axis that would get thinner than they may are gathered into weeks, months … `full` draws every point and eve… |
| segmentColors | "shades" \| "series" | "shades" | `segmented-bar`: colours of the three value tiers (lower, middle and upper third of the axis), bottom to top. `shades` (default): three steps of the series colour, dark → medium → light. `series`: indigo, pink and blue from the standard or… |
| selectedRange | ChartRange \| null |  | The selected range as inclusive indices `[from, to]` into `data`, to control it yourself. `null` selects nothing. |
| showValues | boolean |  | Value labels at the bars (on by default for labelled, top-k and butterfly). |
| state | "ready" \| "loading" \| "empty" \| "error" |  | `loading` shows the chart-shaped skeleton, `empty` and `error` a message in the plot. |
| texture | "dots" \| "diagonal" \| "grid" |  | `dots`, `diagonal` or `grid`: a quiet background texture in place of the grid lines (never both), in the grid colour and faded at all four edges; the zero line stays. |
| threshold | number |  | `threshold-bar`: bars at or above it keep their colour, the others turn grey. |
| thresholdLabel | string |  | Label of the threshold tag. Default "Target <value>". |
| tooltip | boolean |  | Tooltip on hover / keyboard focus. Default true. |
| tooltipTitle | (datum: ChartDatum, index: number) => React.ReactNode |  | Title line of the tooltip; defaults to the category label. |
| topK | number | 6 | `top-k-with-others`: how many categories keep their own bar (default 6); the rest are summed. |
| trendline | boolean \| readonly string[] |  | Linear trend (least squares), dotted in a lighter step of the series colour: `true` for every series or a list of series keys. |
| valueAxis | boolean |  | Value-axis labels (default true). Off for compact cards and sparkline-like plots. |
| valueAxisPlacement | "auto" \| "outside" \| "inside" |  | Where the value labels go: `outside` left of the plot, `inside` in the plot above their grid lines (saves the label column on narrow charts). `auto` (default) puts them left of the plot at every size; `inside` is opt-in. |
| valueAxisSide | "left" \| "right" |  | Side of the value axis (vertical charts). `right` is the price axis of trading charts. |
| valueDomain | readonly [number, number] |  | Fix the value domain instead of fitting it to the data (still rounded to nice steps). |
| valueFormatter | ChartValueFormatter |  | Values in tooltip, labels, table and live region. Default: 42000 → "42k". |
| valueTicks | readonly number[] |  | Exact value-axis ticks (ascending), e.g. [0, 10000, … 70000]; replaces the nice-step domain. |
| variant | "basic-bar" \| "grouped-bar" \| "stroke-bar" \| "gradient-bar" \| "dashed-bar" \| "duotone-bar" \| "stripped-bar" \| "horizontal-bar" \| "negative-bar" \| "lollipop" \| "labelled-bar" \| "threshold-bar" \| "top-k-with-others" \| "butterfly-chart" \| "track-bar" \| "capsule-bar" \| "highlighted-bar" \| "segmented-bar" \| "grouped-bar-3-series" \| "mirrored-bar" \| "dense-bar" \| "horizontal-grouped-bar" \| "tick-bar" \| "3d-bar" \| "square-bar" | "basic-bar" | Figma variant. Default `basic-bar`. |
| width | number |  | Fixed width instead of filling and measuring the container. |
| xScale | "band" \| "time" |  | `band` (default): the categories sit side by side in equal bands. `time`: the `index` field holds dates (Date, ms or a string such as "2026-03-01"); points sit at their real distance, the axis picks its tick level (hours → days → weeks → m… |

## Examples

### States

### Patterns

### Forecast

### Trendline

### Event markers

### Range

### Background texture

### Ghost trail

### Legend on small cards

### Table view

## In context

### Daily Sales vs Previous Period

Store analytics: daily sales grouped against the previous period. Reload shows the loading state.

### Top Pages and Sources

Site analytics: the largest sources or pages, with the rest summed into Others.

### Income vs Expenses

Profit and loss: income up, expenses down per month, with KPI cards.

## For AI agents

`get_component("bar-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
