---
title: BarChart
description: Visualize categorical data with vertical bars.
icon: chart-bar
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

BarChart renders one or more data series as vertical bars. Each `ChartSeries` maps a key from your data to a set of bars, and `x_axis` controls the category labels along the bottom. Colors are automatically assigned from the theme's chart palette.

## Basic Usage

<ComponentPreview json={{"view":{"type":"BarChart","data":[{"month":"Jan","desktop":186,"mobile":80},{"month":"Feb","desktop":305,"mobile":200},{"month":"Mar","desktop":237,"mobile":120},{"month":"Apr","desktop":73,"mobile":190},{"month":"May","desktop":209,"mobile":130},{"month":"Jun","desktop":214,"mobile":140}],"series":[{"dataKey":"desktop","label":"Desktop"},{"dataKey":"mobile","label":"Mobile"}],"xAxis":"month","height":300,"stacked":false,"horizontal":false,"barRadius":4,"showLegend":true,"showTooltip":true,"showGrid":true}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import BarChart, ChartSeries

data = [
    {"month": "Jan", "desktop": 186, "mobile": 80},
    {"month": "Feb", "desktop": 305, "mobile": 200},
    {"month": "Mar", "desktop": 237, "mobile": 120},
    {"month": "Apr", "desktop": 73, "mobile": 190},
    {"month": "May", "desktop": 209, "mobile": 130},
    {"month": "Jun", "desktop": 214, "mobile": 140},
]

BarChart(
    data=data,
    series=[
        ChartSeries(data_key="desktop", label="Desktop"),
        ChartSeries(data_key="mobile", label="Mobile"),
    ],
    x_axis="month",
    show_legend=True,
)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "BarChart",
    "data": [
      {
        "month": "Jan",
        "desktop": 186,
        "mobile": 80
      },
      {
        "month": "Feb",
        "desktop": 305,
        "mobile": 200
      },
      {
        "month": "Mar",
        "desktop": 237,
        "mobile": 120
      },
      {
        "month": "Apr",
        "desktop": 73,
        "mobile": 190
      },
      {
        "month": "May",
        "desktop": 209,
        "mobile": 130
      },
      {
        "month": "Jun",
        "desktop": 214,
        "mobile": 140
      }
    ],
    "series": [
      {
        "dataKey": "desktop",
        "label": "Desktop"
      },
      {
        "dataKey": "mobile",
        "label": "Mobile"
      }
    ],
    "xAxis": "month",
    "height": 300,
    "stacked": false,
    "horizontal": false,
    "barRadius": 4,
    "showLegend": true,
    "showTooltip": true,
    "showGrid": true
  }
}
```
</CodeGroup>
</ComponentPreview>

## Stacked

Set `stacked=True` to stack series on top of each other instead of placing them side by side. This is useful when you want to show both individual values and the total.

<ComponentPreview json={{"view":{"type":"BarChart","data":[{"month":"Jan","desktop":186,"mobile":80},{"month":"Feb","desktop":305,"mobile":200},{"month":"Mar","desktop":237,"mobile":120},{"month":"Apr","desktop":73,"mobile":190},{"month":"May","desktop":209,"mobile":130},{"month":"Jun","desktop":214,"mobile":140}],"series":[{"dataKey":"desktop","label":"Desktop"},{"dataKey":"mobile","label":"Mobile"}],"xAxis":"month","height":300,"stacked":true,"horizontal":false,"barRadius":4,"showLegend":true,"showTooltip":true,"showGrid":true}}}>
<CodeGroup>
```python Python {8} icon="python"
BarChart(
    data=data,
    series=[
        ChartSeries(data_key="desktop", label="Desktop"),
        ChartSeries(data_key="mobile", label="Mobile"),
    ],
    x_axis="month",
    stacked=True,
    show_legend=True,
)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "BarChart",
    "data": [
      {
        "month": "Jan",
        "desktop": 186,
        "mobile": 80
      },
      {
        "month": "Feb",
        "desktop": 305,
        "mobile": 200
      },
      {
        "month": "Mar",
        "desktop": 237,
        "mobile": 120
      },
      {
        "month": "Apr",
        "desktop": 73,
        "mobile": 190
      },
      {
        "month": "May",
        "desktop": 209,
        "mobile": 130
      },
      {
        "month": "Jun",
        "desktop": 214,
        "mobile": 140
      }
    ],
    "series": [
      {
        "dataKey": "desktop",
        "label": "Desktop"
      },
      {
        "dataKey": "mobile",
        "label": "Mobile"
      }
    ],
    "xAxis": "month",
    "height": 300,
    "stacked": true,
    "horizontal": false,
    "barRadius": 4,
    "showLegend": true,
    "showTooltip": true,
    "showGrid": true
  }
}
```
</CodeGroup>
</ComponentPreview>

## Minimal

Turn off the grid for a cleaner look.

<ComponentPreview json={{"view":{"type":"BarChart","data":[{"month":"Jan","desktop":186,"mobile":80},{"month":"Feb","desktop":305,"mobile":200},{"month":"Mar","desktop":237,"mobile":120},{"month":"Apr","desktop":73,"mobile":190},{"month":"May","desktop":209,"mobile":130},{"month":"Jun","desktop":214,"mobile":140}],"series":[{"dataKey":"revenue","label":"Revenue"}],"xAxis":"month","height":300,"stacked":false,"horizontal":false,"barRadius":4,"showLegend":false,"showTooltip":true,"showGrid":false}}}>
<CodeGroup>
```python Python {5} icon="python"
BarChart(
    data=data,
    series=[ChartSeries(data_key="revenue", label="Revenue")],
    x_axis="month",
    show_grid=False,
)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "BarChart",
    "data": [
      {
        "month": "Jan",
        "desktop": 186,
        "mobile": 80
      },
      {
        "month": "Feb",
        "desktop": 305,
        "mobile": 200
      },
      {
        "month": "Mar",
        "desktop": 237,
        "mobile": 120
      },
      {
        "month": "Apr",
        "desktop": 73,
        "mobile": 190
      },
      {
        "month": "May",
        "desktop": 209,
        "mobile": 130
      },
      {
        "month": "Jun",
        "desktop": 214,
        "mobile": 140
      }
    ],
    "series": [
      {
        "dataKey": "revenue",
        "label": "Revenue"
      }
    ],
    "xAxis": "month",
    "height": 300,
    "stacked": false,
    "horizontal": false,
    "barRadius": 4,
    "showLegend": false,
    "showTooltip": true,
    "showGrid": false
  }
}
```
</CodeGroup>
</ComponentPreview>

## Horizontal

Set `horizontal=True` to render bars horizontally. Categories appear along the y-axis and values extend to the right.

<ComponentPreview json={{"view":{"type":"BarChart","data":[{"month":"Jan","desktop":186,"mobile":80},{"month":"Feb","desktop":305,"mobile":200},{"month":"Mar","desktop":237,"mobile":120},{"month":"Apr","desktop":73,"mobile":190},{"month":"May","desktop":209,"mobile":130},{"month":"Jun","desktop":214,"mobile":140}],"series":[{"dataKey":"desktop","label":"Desktop"},{"dataKey":"mobile","label":"Mobile"}],"xAxis":"month","height":300,"stacked":false,"horizontal":true,"barRadius":4,"showLegend":true,"showTooltip":true,"showGrid":true}}}>
<CodeGroup>
```python Python {8} icon="python"
BarChart(
    data=data,
    series=[
        ChartSeries(data_key="desktop", label="Desktop"),
        ChartSeries(data_key="mobile", label="Mobile"),
    ],
    x_axis="month",
    horizontal=True,
    show_legend=True,
)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "BarChart",
    "data": [
      {
        "month": "Jan",
        "desktop": 186,
        "mobile": 80
      },
      {
        "month": "Feb",
        "desktop": 305,
        "mobile": 200
      },
      {
        "month": "Mar",
        "desktop": 237,
        "mobile": 120
      },
      {
        "month": "Apr",
        "desktop": 73,
        "mobile": 190
      },
      {
        "month": "May",
        "desktop": 209,
        "mobile": 130
      },
      {
        "month": "Jun",
        "desktop": 214,
        "mobile": 140
      }
    ],
    "series": [
      {
        "dataKey": "desktop",
        "label": "Desktop"
      },
      {
        "dataKey": "mobile",
        "label": "Mobile"
      }
    ],
    "xAxis": "month",
    "height": 300,
    "stacked": false,
    "horizontal": true,
    "barRadius": 4,
    "showLegend": true,
    "showTooltip": true,
    "showGrid": true
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="BarChart Parameters">
<ParamField body="data" type="list[dict] | str" required>
  Data as a list of dicts, or a `{{ field }}` interpolation reference.
</ParamField>

<ParamField body="series" type="list[ChartSeries]" required>
  Series definitions — each becomes a group of bars on the chart.
</ParamField>

<ParamField body="x_axis" type="str | None" default="None">
  Data key for x-axis category labels.
</ParamField>

<ParamField body="height" type="int" default="300">
  Chart height in pixels.
</ParamField>

<ParamField body="stacked" type="bool" default="False">
  Stack series on top of each other.
</ParamField>

<ParamField body="horizontal" type="bool" default="False">
  Render bars horizontally instead of vertically.
</ParamField>

<ParamField body="bar_radius" type="int" default="4">
  Corner radius of each bar in pixels.
</ParamField>

<ParamField body="show_legend" type="bool" default="False">
  Show a legend below the chart.
</ParamField>

<ParamField body="show_tooltip" type="bool" default="True">
  Show tooltips on hover.
</ParamField>

<ParamField body="show_grid" type="bool" default="True">
  Show horizontal grid lines.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes.
</ParamField>
</Card>

<Card icon="code" title="ChartSeries Parameters">
<ParamField body="data_key" type="str" required>
  Data field to plot — must match a key in the data dicts.
</ParamField>

<ParamField body="label" type="str | None" default="None">
  Display label for legends and tooltips. Defaults to the `data_key` value.
</ParamField>

<ParamField body="color" type="str | None" default="None">
  CSS color override. By default, colors cycle through the theme's chart palette (`--chart-1` through `--chart-5`).
</ParamField>
</Card>

## Protocol Reference

```json BarChart
{
  "type": "BarChart",
  "data": "Action[] | string (required)",
  "series": "[ChartSeries] (required)",
  "xAxis?": "string",
  "height?": "300",
  "stacked?": false,
  "horizontal?": false,
  "barRadius?": 4,
  "showLegend?": false,
  "showTooltip?": true,
  "showGrid?": true,
  "cssClass?": "string"
}
```

```json ChartSeries
{
  "dataKey": "string (required)",
  "label?": "string",
  "color?": "string"
}
```

For the complete protocol schema, see [BarChart](/protocol/bar-chart), [ChartSeries](/protocol/chart-series).
