# Bar Chart (/docs/charts/components/bar)

Use a bar chart to compare a measure across categories, like locations or products, and to compare a few measures side by side or stacked.

<Example caption="Hover a bar, or focus the chart and press the arrow keys, to see its value and dim the other bars.">
<Basic />

```tsx
"use client";

import { BarChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { location: "North", orders: 124 },
  { location: "East", orders: 186 },
  { location: "Central", orders: 238 },
  { location: "West", orders: 162 },
  { location: "South", orders: 208 },
];

const config = {
  orders: { label: "Orders", color: "#733bff" },
} satisfies SeriesConfig;

export default function OrdersChart() {
  return (
    <BarChart
      data={data}
      config={config}
      animate
      emphasis="category"
      aria-label="Weekly pickup orders by location"
    >
      <BarChart.Grid vertical={false} />
      <BarChart.XAxis dataKey="location" />
      <BarChart.YAxis width={40} />
      <BarChart.Series dataKey="orders" radius={[4, 4, 0, 0]} maxBarSize={48} />
      <BarChart.Tooltip />
      <BarChart.Legend />
    </BarChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/bar-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
BarChart
├── BarChart.Background
├── BarChart.Grid
├── BarChart.XAxis
├── BarChart.YAxis
├── BarChart.Series
│   ├── BarChart.Cell
│   └── BarChart.Labels
├── BarChart.Tooltip
├── BarChart.Legend
└── BarChart.Content
```

`BarChart` holds the data, the series config and the accessible name, and draws only the parts you add. Add one `BarChart.Series` per measure. `BarChart.Cell` colors a single bar and `BarChart.Labels` writes values on the bars. The tooltip and legend read their labels and colors from `config`. `BarChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Series [#series]

Each `BarChart.Series` plots the `dataKey` it names, and takes its label and color from the matching `config` entry. Series sit side by side in each category. Set `radius` to round the corners and `maxBarSize` to cap the width:

<Example caption="Press Print or Digital in the legend to highlight that series.">
<Comparison />

```tsx
"use client";

import { BarChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { subject: "Fiction", print: 184, digital: 116 },
  { subject: "History", print: 128, digital: 72 },
  { subject: "Science", print: 156, digital: 104 },
  { subject: "Arts", print: 112, digital: 88 },
  { subject: "Travel", print: 96, digital: 64 },
];

const config = {
  print: { label: "Print", color: "#733bff" },
  digital: { label: "Digital", color: "#14a39a" },
} satisfies SeriesConfig;

export default function LoansChart() {
  return (
    <BarChart data={data} config={config} animate aria-label="Library loans by subject and format">
      <BarChart.Grid vertical={false} />
      <BarChart.XAxis dataKey="subject" />
      <BarChart.YAxis width={40} />
      <BarChart.Series dataKey="print" maxBarSize={32} />
      <BarChart.Series dataKey="digital" maxBarSize={32} />
      <BarChart.Tooltip />
      <BarChart.Legend />
    </BarChart>
  );
}
```
</Example>

Give series the same `stackId` to stack them. Set `stackOffset="expand"` on the chart to stack to 100%, or `"sign"` to stack negative values below zero:

```tsx
<BarChart.Series dataKey="print" stackId="loans" />
<BarChart.Series dataKey="digital" stackId="loans" />
```

### Horizontal Bars [#horizontal-bars]

Set `layout="vertical"` for horizontal bars. The axes swap, so the X axis is the number scale and the Y axis names the categories:

```tsx
<BarChart layout="vertical" {...props}>
  <BarChart.XAxis type="number" />
  <BarChart.YAxis type="category" dataKey="location" width={80} />
  <BarChart.Series dataKey="orders" radius={[0, 4, 4, 0]} />
</BarChart>
```

### Emphasis [#emphasis]

By default, hovering a bar dims the other series. Set `emphasis="category"` to dim the other categories instead, as in the first example, or `"none"` to turn it off. Category emphasis reads each row's category from the category axis, so those categories must be unique strings. When they aren't, like numbers or repeated labels, pass the series an `emphasisKey` that returns a unique key for each row. A custom `shape`, range values or per-series `data` turn it off for that chart.

### Legend and Keyboard [#legend-and-keyboard]

Pressing a legend item highlights its series and dims the others, and screen readers hear "Highlighted Print." Press it again, or press Escape, to clear it. Hidden series keep their slot in each group, and stacks keep their baselines. To hide and show series from the legend instead, see [Legend](../building-blocks/legend.mdx).

Focus the chart and press the arrow keys to move between categories, which shows the tooltip, and Escape to dismiss it.

### Patterns and Projections [#patterns-and-projections]

Give a series a `pattern` in `config` to fill its bars with `hatch`, `stripe`, `duotone`, `dots` or `lines`, and its legend swatch follows. To pattern only some bars, like projected values, pass `projection` with a function that picks them:

```tsx
<BarChart.Series
  dataKey="orders"
  projection={{ isProjected: (row) => row.projected, pattern: { kind: "stripe" } }}
/>
```

The chart only draws the values you pass; it doesn't forecast them. An explicit `fill`, `BarChart.Cell` or custom `shape` replaces the pattern.

Set `material="clay"` or `"glow"` on a series for a finish; see [Materials](../guides/materials.mdx).

### Motion [#motion]

Set `animate` to grow the bars from zero when the chart mounts, over one second by default. Pass options to change the duration or easing:

```tsx
<BarChart animate={{ revealDurationMs: 600 }} {...props}>
```

When the reader prefers reduced motion, bars appear without growing. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows placeholder bars that rise and fade, or hold still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default). The legend and tooltip come back when `loading` turns off:

```tsx
<BarChart loading={isPending} loadingLabel="Loading orders" {...props}>
```

## API Reference [#api-reference]

### BarChart [#barchart]

### BarChartOptions

| Prop                     | Type                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data?`                  | `ChartData<unknown> \| undefined`                                                                                                                                                                                                                    | The source data. Each element should be an object. The properties of each object represent the values of different data dimensions. Use the `dataKey` prop to specify which properties to use. |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show, when you control visibility.                                                                                                                                          |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show first, when the chart controls visibility.                                                                                                                             |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                              | Called with the next visible series keys when the legend hides or shows one.                                                                                                                   |
| `animate?`               | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                              | Grows the bars from zero on mount. Pass options to change the duration or easing. Reduced motion skips it. Default: `false`                                                                    |
| `loading?`               | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                                                                                        |
| `loadingLabel?`          | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                                                                     |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                                                                                       |
| `interaction?`           | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                                                                                        |
| `aria-label?`            | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                                                                                   |
| `aria-labelledby?`       | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                                                                                          |
| `legendPosition?`        | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                                                                                            |
| `frameProps?`            | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                                                                                         |
| `emphasis?`              | `"auto" \| "category" \| "none"`                                                                                                                                                                                                                     | Dims the other series while one is hovered or focused. `"category"` dims the other categories instead, while a bar is inspected. `"none"` turns it off. Default: `"auto"`                      |

### BarChart.Series [#barchartseries]

### BarSeriesOptions

| Prop           | Type                                                                 | Description                                                                                                                                                      |
| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seriesKey?`   | `string \| undefined`                                                | The series' key in `config`, for its label, color and visibility. Required when `dataKey` is a function or a number. Default: `dataKey`                          |
| `emphasisKey?` | `((payload: unknown) => string \| number \| undefined) \| undefined` | Returns a row's category, for `emphasis="category"` when categories aren't unique strings.                                                                       |
| `material?`    | `"clay" \| "glow" \| "plain"`                                        | A finish for the bars: `"clay"` or `"glow"`. A custom `shape` or `filter` replaces it. Default: `"plain"`                                                        |
| `pattern?`     | `false \| FillPattern \| undefined`                                  | Fills the bars with a pattern instead of a solid color. Overrides the `config` pattern; `false` turns it off. An explicit `fill`, `Cell` or `shape` replaces it. |
| `projection?`  | `BarProjection<unknown> \| undefined`                                | Patterns the rows `isProjected` picks, like forecast values. It doesn't compute them.                                                                            |

<Caption>
`BarChart` and `BarChart.Series` also take every prop of Recharts' [BarChart](https://recharts.github.io/en-US/api/BarChart/) and [Bar](https://recharts.github.io/en-US/api/Bar/), like `layout`, `stackOffset`, `stackId`, `radius` and `maxBarSize`.
</Caption>