# Bar charts

> Grouped, stacked, horizontal and distributed bars with barChart(), and how to space them.

A bar chart takes the same data as a line chart: labels along one axis, a series per array. Each value becomes a bar that grows from zero, so the axis includes zero (unless you [set `low` or `high`](#low-and-high)) and negative values hang below it.

`barChart()` takes a container, your data and options. The data shapes are shared by all chart types and explained in [Data and options](https://chartist.dev/docs/data-and-options/).

## Grouped bars

Several series put their bars side by side, one group per label:

**Grouped bars** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import { barChart } from 'chartist';

barChart('#chart', {
  labels: ['Jan', 'Feb', 'Mar', 'Apr'],
  series: [
    [5, 4, 3, 7],
    [3, 2, 9, 5],
    [1, 5, 8, 4]
  ]
});
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

A `null` value leaves its bar out and keeps its place in the group.

## Bar spacing

Two settings shape a group, and they live in different places. The distance between the bars of a group is layout, so it's an option: `seriesBarDistance`, in pixels, `15` by default. The thickness of a bar is looks, so it's CSS: bars are SVG lines, and `--ct-bar-width` (`10px` by default) sets their stroke width.

**Wider bars, further apart** (runs in the browser):

`src/style.css`:

```css
#chart {
  --ct-bar-width: 20px;
}
```

`src/main.ts`:

```ts
import 'chartist/styles.css';
import './style.css';
import { barChart } from 'chartist';

barChart(
  '#chart',
  {
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
    series: [
      [5, 4, 3, 7],
      [3, 2, 9, 5]
    ]
  },
  { seriesBarDistance: 24 }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

Keep `seriesBarDistance` at least as large as the bar width, or the bars of a group overlap. More about the custom properties in [Styling with CSS](https://chartist.dev/docs/styling-with-css/#custom-properties).

## Stacked bars

With `stackBars: true`, the series of a label stack into one bar, and the value axis grows to fit the totals. `seriesBarDistance` has no effect here.

**Stacked bars** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import { barChart } from 'chartist';

barChart(
  '#chart',
  {
    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
    series: [
      [800, 1200, 1400, 1300],
      [200, 400, 500, 300],
      [100, 200, 400, 600]
    ]
  },
  { stackBars: true }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

### Stack modes

`stackMode` decides what happens when values have different signs:

| `stackMode`              | The stack                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `'accumulate'` (default) | A running total: each bar starts where the previous one ended, so a negative value goes back down. |
| `'accumulate-relative'`  | Positive values stack up from zero, negative values stack down from zero.                          |
| `'overlap'` or `true`    | No stacking: every bar starts at zero and they overlap, the first series at the back.              |

`'accumulate-relative'` is the one for gains and losses:

```ts
import 'chartist/styles.css';
import { barChart } from 'chartist';

barChart(
  '#chart',
  {
    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
    series: [
      [5, 4, 6, 8],
      [-3, -1, -4, -2]
    ]
  },
  { stackBars: true, stackMode: 'accumulate-relative' }
);
```

The value axis fits both sides: up to the highest stack above zero and down to the lowest one below it.

## Horizontal bars

`horizontalBars: true` turns the chart on its side: the labels move to the Y axis and the values to the X axis. The axis options move with them, so the label settings now go in `axisY`. Long labels need a wider `offset`:

**Horizontal bars** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import { barChart } from 'chartist';

barChart(
  '#chart',
  {
    labels: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
    series: [
      [5, 4, 3, 7, 5],
      [3, 2, 9, 5, 4]
    ]
  },
  {
    horizontalBars: true,
    // The labels are on the Y axis now: give them room.
    axisY: { offset: 70 }
  }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

The chart gets the `ct-horizontal-bars` class next to `ct-chart-bar`, for styles that only apply to horizontal bars.

## Distributed series

Sometimes every bar is its own thing: sizes, categories, a profile rather than values over time. Pass a flat array of values and set `distributeSeries: true`. Each value becomes its own series, `ct-series-a`, `ct-series-b` and so on, so every bar gets its own color:

**Distributed series** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import { barChart } from 'chartist';

// A flat array: one value per label, and each bar is its own series.
barChart(
  '#chart',
  {
    labels: ['XS', 'S', 'M', 'L', 'XL'],
    series: [20, 60, 120, 200, 180]
  },
  { distributeSeries: true }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

## Low and high

`low` and `high` fix the ends of the value axis, as on line charts, and so do the value axis's own (`axisY: { low: 10 }`). Bars still start at zero: with a `low` above zero, the bars start at the bottom edge of the chart. The axis settings are in [Axes and scales](https://chartist.dev/docs/axes-and-scales/).

```ts
import 'chartist/styles.css';
import { barChart } from 'chartist';

barChart(
  '#chart',
  {
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
    series: [[5, 4, 3, 7]]
  },
  { high: 10 }
);
```

In the API reference: [`barChart`](https://chartist.dev/api/charts/#barChart) and [its options](https://chartist.dev/api/charts/#BarChartPresetOptions).

Next: [line charts](https://chartist.dev/docs/line-charts/), or [make bars respond to the screen](https://chartist.dev/docs/responsive/).