# Bars

Printed bars on the panel, one value each. The bars are ink laid flat on the plate, never a colour and never glass; the axis is engraved into it, a groove along the zero line with the light on its lower lip and a faint rule at each tick. The values are a real list, one item a bar, so a screen reader reads “Thu, 73” and the picture is drawn over it. Columns by default, rows when the labels are long, and on display glass the ink is the display’s light.

Kit part · Free · https://tactileui.dev/parts/bars

- Element: `<figure class="tui-bars">`
- Needs: `kit.css` only, no script ([how to install the kit](https://tactileui.dev/docs/installation#the-kit))
- Categories: Charts
- Finishes: Aluminium, Graphite, Oak, Walnut, Porcelain, Black, Daylight, Night, Paper, Phosphor, E-paper, AMOLED
- Volumes: Tactile, Quiet

## Variants

### Columns · with the highest marked

```html
<div style="width:min(420px,calc(100vw - 96px));text-align:left"><figure class="tui-bars" style="--max:80"><figcaption class="tui-label tui-bars__title">Builds per day</figcaption><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:20">20</span><span style="--at:40">40</span><span style="--at:60">60</span><span style="--at:80">80</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:42"><span class="tui-bars__label">Mon</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">42</span></span></li><li class="tui-bars__item" style="--v:58"><span class="tui-bars__label">Tue</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">58</span></span></li><li class="tui-bars__item" style="--v:51"><span class="tui-bars__label">Wed</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">51</span></span></li><li class="tui-bars__item" style="--v:73" data-mark><span class="tui-bars__label">Thu</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">73<span class="tui-bars__said">, highest</span></span></span></li><li class="tui-bars__item" style="--v:66"><span class="tui-bars__label">Fri</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">66</span></span></li><li class="tui-bars__item" style="--v:24"><span class="tui-bars__label">Sat</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">24</span></span></li><li class="tui-bars__item" style="--v:18"><span class="tui-bars__label">Sun</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">18</span></span></li></ul></div></figure></div>
```

### Rows · .tui-bars--row

```html
<div style="width:min(440px,calc(100vw - 96px));text-align:left"><figure class="tui-bars tui-bars--row" style="--max:150"><figcaption class="tui-label tui-bars__title">Berths booked by office</figcaption><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:50">50</span><span style="--at:100">100</span><span style="--at:150">150</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:128"><span class="tui-bars__label">Harbour</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">128</span></span></li><li class="tui-bars__item" style="--v:96"><span class="tui-bars__label">Quay Street</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">96</span></span></li><li class="tui-bars__item" style="--v:71"><span class="tui-bars__label">Dockside</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">71</span></span></li><li class="tui-bars__item" style="--v:33"><span class="tui-bars__label">Pilot office</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">33</span></span></li></ul></div></figure></div>
```

### Twelve columns · narrow

```html
<div style="width:min(380px,calc(100vw - 96px));text-align:left"><figure class="tui-bars" style="--max:60"><figcaption class="tui-label tui-bars__title">Bookings by month</figcaption><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:20">20</span><span style="--at:40">40</span><span style="--at:60">60</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:12"><span class="tui-bars__label">Jan</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">12</span></span></li><li class="tui-bars__item" style="--v:18"><span class="tui-bars__label">Feb</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">18</span></span></li><li class="tui-bars__item" style="--v:15"><span class="tui-bars__label">Mar</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">15</span></span></li><li class="tui-bars__item" style="--v:22"><span class="tui-bars__label">Apr</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">22</span></span></li><li class="tui-bars__item" style="--v:30"><span class="tui-bars__label">May</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">30</span></span></li><li class="tui-bars__item" style="--v:41"><span class="tui-bars__label">Jun</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">41</span></span></li><li class="tui-bars__item" style="--v:38"><span class="tui-bars__label">Jul</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">38</span></span></li><li class="tui-bars__item" style="--v:35"><span class="tui-bars__label">Aug</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">35</span></span></li><li class="tui-bars__item" style="--v:28"><span class="tui-bars__label">Sep</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">28</span></span></li><li class="tui-bars__item" style="--v:24"><span class="tui-bars__label">Oct</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">24</span></span></li><li class="tui-bars__item" style="--v:19"><span class="tui-bars__label">Nov</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">19</span></span></li><li class="tui-bars__item" style="--v:14"><span class="tui-bars__label">Dec</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">14</span></span></li></ul></div></figure></div>
```

### On display glass · the display’s light

```html
<div class="tui-glass" style="width:min(100%,420px);text-align:left"><figure class="tui-bars" style="--max:80"><figcaption class="tui-label tui-bars__title">Builds per day</figcaption><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:20">20</span><span style="--at:40">40</span><span style="--at:60">60</span><span style="--at:80">80</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:42"><span class="tui-bars__label">Mon</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">42</span></span></li><li class="tui-bars__item" style="--v:58"><span class="tui-bars__label">Tue</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">58</span></span></li><li class="tui-bars__item" style="--v:51"><span class="tui-bars__label">Wed</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">51</span></span></li><li class="tui-bars__item" style="--v:73" data-mark><span class="tui-bars__label">Thu</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">73<span class="tui-bars__said">, highest</span></span></span></li><li class="tui-bars__item" style="--v:66"><span class="tui-bars__label">Fri</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">66</span></span></li><li class="tui-bars__item" style="--v:24"><span class="tui-bars__label">Sat</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">24</span></span></li><li class="tui-bars__item" style="--v:18"><span class="tui-bars__label">Sun</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">18</span></span></li></ul></div></figure></div>
```

### A zero among them

```html
<div style="width:min(320px,calc(100vw - 96px));text-align:left"><figure class="tui-bars" style="--max:6"><figcaption class="tui-label tui-bars__title">Fuel stops</figcaption><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:2">2</span><span style="--at:4">4</span><span style="--at:6">6</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:3"><span class="tui-bars__label">Mon</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">3</span></span></li><li class="tui-bars__item" style="--v:0"><span class="tui-bars__label">Tue</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">0</span></span></li><li class="tui-bars__item" style="--v:5"><span class="tui-bars__label">Wed</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">5</span></span></li><li class="tui-bars__item" style="--v:2"><span class="tui-bars__label">Thu</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">2</span></span></li></ul></div></figure></div>
```

### No caption · named by aria-label

```html
<div style="width:min(300px,calc(100vw - 96px));text-align:left"><figure class="tui-bars" style="--max:80" aria-label="Builds per day"><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:20">20</span><span style="--at:40">40</span><span style="--at:60">60</span><span style="--at:80">80</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:42"><span class="tui-bars__label">Mon</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">42</span></span></li><li class="tui-bars__item" style="--v:58"><span class="tui-bars__label">Tue</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">58</span></span></li><li class="tui-bars__item" style="--v:51"><span class="tui-bars__label">Wed</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">51</span></span></li><li class="tui-bars__item" style="--v:73"><span class="tui-bars__label">Thu</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">73</span></span></li></ul></div></figure></div>
```

## Every state

- Columns
- Rows
- A marked bar
- On glass

Hover, pressed and focus are forced with `.is-hover`, `.is-down` and `.is-focus`; checked and disabled are real.

## API

| Name | Kind | Values | What it does |
| - | - | - | - |
| figure.tui-bars[style="--max"] | element | a number | The figure. --max is the value at the top of the axis; every --v and --at is in the same unit. Add --row for rows. |
| figcaption.tui-label.tui-bars__title | element | what and the unit | Names the figure and says the unit (“Latency, ms”), because the list reads out only the figures. Without a caption, give the figure an aria-label. |
| .tui-bars__axis[aria-hidden] | element | spans with --at | The engraved axis, for the eye only. The first tick is the zero line, drawn as a groove; the others are faint rules. |
| ul.tui-bars__set[role="list"] | element | one li per bar | The values, as a real list. role="list" keeps it a list for a screen reader after the list style is taken off. |
| li.tui-bars__item[style="--v"] | element | a number | One bar: a label, then a slot holding the bar (aria-hidden) and its printed value. data-mark hatches and outlines the bar and bolds its label. |
| .tui-bars__said | class | inside the value | Words for a screen reader only (“, highest”), so a marked bar is not marked by looks alone. |
| --bars-h · --bars-row-h · --bars-label | custom property | lengths | The height of a column chart, the height of a row, and the width of the label column in rows. |
| barsHTML(options) · barsScale(max, count) | function | pure | The whole figure, and a top and ticks on whole steps of 1, 2 or 5. |

## Markup

```html
<!-- A figure with a caption, a real list of the values, and an axis drawn over it. --max and --v share a unit. -->
<figure class="tui-bars" style="--max:80">
  <figcaption class="tui-label tui-bars__title">Builds per day</figcaption>
  <div class="tui-bars__chart">
    <div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:40">40</span><span style="--at:80">80</span></div>
    <ul class="tui-bars__set" role="list">
      <li class="tui-bars__item" style="--v:42"><span class="tui-bars__label">Mon</span>
        <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">42</span></span></li>
      <li class="tui-bars__item" style="--v:73" data-mark><span class="tui-bars__label">Thu</span>
        <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">73<span class="tui-bars__said">, highest</span></span></span></li>
    </ul>
  </div>
</figure>

<!-- Rows: add tui-bars--row to the figure. -->
```

```js
import { barsHTML, barsScale } from '/kit/kit.mjs';

barsScale(73);   // { max: 80, ticks: [0, 20, 40, 60, 80] }  whole steps of 1, 2 or 5

figure.outerHTML = barsHTML({
  title: 'Builds per day',
  items: [{ label: 'Mon', value: 42 }, { label: 'Thu', value: 73, mark: true, note: 'highest' }],
  orient: 'column',   // or 'row'
});
```

The demo on the page:

```html
<div class="tui-panel" style="width:min(100%,560px);display:grid;gap:16px;text-align:left"><div class="tui-panel__head" style="margin-bottom:0"><span class="tui-label">Builds · Northwind</span></div><div data-br-host><figure class="tui-bars" style="--max:80"><figcaption class="tui-label tui-bars__title">Builds per day</figcaption><div class="tui-bars__chart"><div class="tui-bars__axis" aria-hidden="true"><span style="--at:0">0</span><span style="--at:20">20</span><span style="--at:40">40</span><span style="--at:60">60</span><span style="--at:80">80</span></div><ul class="tui-bars__set" role="list"><li class="tui-bars__item" style="--v:42"><span class="tui-bars__label">Mon</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">42</span></span></li><li class="tui-bars__item" style="--v:58"><span class="tui-bars__label">Tue</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">58</span></span></li><li class="tui-bars__item" style="--v:51"><span class="tui-bars__label">Wed</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">51</span></span></li><li class="tui-bars__item" style="--v:73" data-mark><span class="tui-bars__label">Thu</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">73<span class="tui-bars__said">, highest</span></span></span></li><li class="tui-bars__item" style="--v:66"><span class="tui-bars__label">Fri</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">66</span></span></li><li class="tui-bars__item" style="--v:24"><span class="tui-bars__label">Sat</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">24</span></span></li><li class="tui-bars__item" style="--v:18"><span class="tui-bars__label">Sun</span> <span class="tui-bars__slot"><span class="tui-bars__bar" aria-hidden="true"></span><span class="tui-bars__value">18</span></span></li></ul></div></figure></div><div style="display:flex;gap:12px;flex-wrap:wrap;align-items:center"><button class="tui-key tui-key--sm" type="button" data-br-change>Change the values</button><button class="tui-key tui-key--sm" type="button" data-br-rows aria-pressed="false">Show as rows</button></div></div>
```

## Usage notes

Press Change the values: the bars slide to their new heights, and the figures and the list change with them. Press Show as rows to lay the same values along rows. The highest bar is hatched and outlined as well as bold, so it does not rely on ink alone.

## Accessibility

- The values are a real `<ul>` of items, each reading its label and then its figure (“Thu, 73”), so a screen reader gets every value in order. The bars and the axis are `aria-hidden`; nothing depends on seeing them.
- A marked bar is hatched, outlined, bold in its label and bold in its figure, and says why in words for a screen reader. Bars are never told apart by colour: there is only ink.
- The figures print at the end of each bar, so nobody has to read a height off an axis. Axis figures are in the secondary ink, above 4.5:1 on the plate in every finish.
- Updating a value moves the bar in 220 ms; under reduced motion it moves at once. The list changes with the picture, so the two cannot disagree.
- Labels shorten with an ellipsis rather than wrap when columns are many; the full text is still in the list. Nothing makes the page scroll sideways at 390px.

## How it’s built

Each bar is ink on the plate with the height set from two numbers in CSS, `--v` over `--max`, so there is no script and no canvas. The axis is a set of spans placed from their own `--at`, with the zero line engraved the way the kit engraves a rule: a dark cut and a lit lower lip, which Quiet draws as a hairline. On glass the ink is the display’s own light.

## Rules

Compare a handful of values side by side: ink bars on the plate, an engraved axis, each value printed at the end of its bar and listed for a screen reader.

The full rules are in `bars.rules.md` in the brain, which ships with the Kit.

## Related parts

- [LED bar chart](https://tactileui.dev/parts/ledbars): A bar chart built like a studio meter bridge: columns of LED segments behind a smoked window, green then amber then red, with a peak segment that lingers and a lit readout for the exact value.
- [Plot](https://tactileui.dev/parts/plot): Line charts drawn as light on glass, or as ink on a panel: gridlines faint, two traces at most, a red line for now.
- [Sparkline](https://tactileui.dev/parts/sparkline): A word-sized line for the margin of a table or beside a readout. It is an SVG that takes the size of the type around it and the ink of the place it sits in, so on a panel it is ink and on display glass it is the display’s light. The last value is marked with a dot seated in a faint ring, and a lamp lights the dot when the reading matters. The trend and the last value are said in words on the image’s label, so the line is a second sign and never the only one.
