# BarChart

Shows values over time as stacked bars, such as the daily spend of each agent.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/BarChart.tsx)

Figma: [Data/Chart Tooltip](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5422) (`BarChart.Tooltip`), [Data/Stacked Bar Chart](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-4523)

## Overview

A bar chart renders one bar per entry of its data, with a segment for each series stacked from the baseline. A value axis with three even ticks leads the plot, labels name the bars under it, and a legend names each series. Hovering a bar, or moving to it with the arrow keys, shows the value of each series. Values are zero or more, such as spend or counts. Chart a signed change, such as a refund, another way.

## Examples

### Basic

```tsx
import { BarChart } from '@tempoxyz/ds'

const days = ['Oct 1', 'Oct 2', 'Oct 3', 'Oct 4', 'Oct 5', 'Oct 6', 'Today']

export function Demo() {
  return (
    <BarChart
      aria-label="Spend by agent"
      data={days.map((day, index) => ({
        claude: [1.2, 0.8, 2.1, 0, 1.6, 2.4, 1.1][index]!,
        codex: [0.4, 0.9, 0.3, 0, 1.2, 0.6, 0.8][index]!,
        day,
      }))}
      format={(value) => `$${value}`}
      index="day"
      series={[
        { color: '#d97757', key: 'claude', label: 'Claude' },
        { color: '#10a37f', key: 'codex', label: 'Codex' },
      ]}
    />
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BarChart/Basic.tsx)

### Ticks

Pass `ticks` to label only some bars, such as every seventh day.

```tsx
import { BarChart } from '@tempoxyz/ds'

const days = Array.from({ length: 30 }, (_, index) => (index === 29 ? 'Today' : `Oct ${index + 1}`))

export function Demo() {
  return (
    <BarChart
      aria-label="Spend over 30 days"
      data={days.map((day, index) => ({ claude: ((index * 7) % 11) / 4, day }))}
      format={(value) => `$${value}`}
      index="day"
      series={[{ color: '#d97757', key: 'claude', label: 'Claude' }]}
      ticks={['Oct 1', 'Oct 8', 'Oct 15', 'Oct 22', 'Today']}
    />
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BarChart/Ticks.tsx)

### Tooltip

`BarChart.Tooltip` renders the card that a hovered bar shows, which also renders alone.

```tsx
import { BarChart } from '@tempoxyz/ds'

export function Demo() {
  return (
    <BarChart.Tooltip
      items={[
        { color: '#0a0a0a', label: 'CLI', value: '$3.27' },
        { color: '#10a37f', label: 'Codex', value: '$0.90' },
        { color: '#1f1f1f', label: 'Cursor', value: '$0.10' },
      ]}
      label="Oct 12"
      total="$4.32"
    />
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/BarChart/Tooltip.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { BarChart } from '@tempoxyz/ds'

<BarChart />
<BarChart.Tooltip />
```

## Guidelines

### When to Use

* Show how a value changes over days or weeks, and which series make it up.

### When Not to Use

* Use [SplitBar](/docs/components/split-bar) to split one total between two parts.
* Use [Table](/docs/components/table) when people need to read or compare exact values.
* Use [Gauge](/docs/components/gauge) for one value against a limit.

### Keep Each Series in One Color

**Do:** Give each series a color that stays the same wherever it appears, such as the agent's own color.

```tsx
import { BarChart } from '@tempoxyz/ds'

const days = ['Oct 1', 'Oct 2', 'Oct 3', 'Today']

export function Demo() {
  return (
    <BarChart
      aria-label="Spend by agent"
      data={days.map((day, index) => ({ claude: index + 1, codex: 1, day }))}
      format={(value) => `$${value}`}
      height={140}
      index="day"
      series={[
        { color: '#d97757', key: 'claude', label: 'Claude' },
        { color: '#10a37f', key: 'codex', label: 'Codex' },
      ]}
    />
  )
}
```

**Don't:** Use the positive and negative colors for series. They mean a status.

```tsx
import { BarChart } from '@tempoxyz/ds'

const days = ['Oct 1', 'Oct 2', 'Oct 3', 'Today']

export function Demo() {
  return (
    <BarChart
      aria-label="Spend by agent"
      data={days.map((day, index) => ({ claude: index + 1, codex: 1, day }))}
      format={(value) => `$${value}`}
      height={140}
      index="day"
      series={[
        { color: '#13a963', key: 'claude', label: 'Claude' },
        { color: '#eb3417', key: 'codex', label: 'Codex' },
      ]}
    />
  )
}
```

### Label a Few Bars

* **Every Bar (up to 7):** Label every bar of a week.
* **Every Seventh Bar (ticks):** Label every seventh bar of a month.

## Content

### Format Values the Same Way

Pass one `format` for the axis, the tooltip, and the total, such as whole dollars. Name each series with the name people know it by, such as Claude.

## Accessibility

A bar chart renders a `<div>` with the `figure` role. Its plot takes focus, and the arrow keys move between bars and show their tooltip.

### Semantics

* **Root (figure):** Screen readers announce the chart by its `aria-label`.
* **Legend (text):** The legend names each series in text, so color is never the only cue.

### Keyboard

* **Move Focus to the Plot (Tab):** Moves focus to the plot, which shows the first bar's tooltip.
* **Move Between Bars (Left or Right Arrow):** Moves to the previous or next bar and shows its tooltip.

### Your Responsibilities

* **Name the Chart (aria-label):** Pass `aria-label`, or `aria-labelledby` pointing at the chart's heading.
* **Offer the Values (Table):** Offer the same values in a [Table](/docs/components/table) when people need exact values.

## Related

[SplitBar](/docs/components/split-bar)

Use for one total split between two parts.

[AgentLogo](/docs/components/agent-logo)

Use for the agent of each series.

[Table](/docs/components/table)

Use for exact values.
