# Bar chart

Columns by category, grouped or stacked. Bars stay thin (24px at most) with a 4px rounded end and a 2px gap between neighbours; a missing value is a dashed stub at the baseline, never a zero-height bar. One series gets a value on each cap; several get a legend. Hover or focus a category for every series' value; the table view lists them all.

- Registry name: `bar-chart` (`@candor/bar-chart`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/bar-chart

## Install

```bash
npx candor-ui add bar-chart
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/bar-chart`.
It brings in: chart-frame, data, locale, scale, utils.

## Example

```tsx
"use client"

import { BarChart } from "@/components/bar-chart"
import type { Series } from "@/lib/data"

const repositories = ["api", "web", "billing", "workers", "infra", "docs"]

const tests: Series[] = [
  { id: "passed", label: "Passed", values: [212, 148, 96, 74, 31, 12] },
  { id: "failed", label: "Failed", values: [3, 0, 5, 1, 0, null] },
]

export default function Example() {
  return <BarChart className="max-w-xl" title="Tests by repository" subtitle="Stacked · last night’s CI run" categories={repositories} series={tests} stacked />
}
```

## <BarChart>

Props:

- `title: string`: What the chart shows, above it.
- `subtitle?: string | undefined`: A line under the title, e.g. the period or unit.
- `categories: string[]`: The column labels along the x axis.
- `series: Series[]`: One value per category per series; null draws a dashed stub.
- `stacked?: boolean | undefined` (default `false`): Stacks series in one column instead of grouping them side by side.
- `format?: ValueFormat | undefined` (default `"number"`): How values are written: number, percent (0–1), currency (USD) or duration (seconds). Defaults to number.
- `state?: ChartState | undefined`: Loading, empty, partial or error. Defaults to ready.
- `height?: number | undefined`: The plot's height in pixels. Defaults to 220.
- `className?: string | undefined`

## Strings (`barChart`)

The fixed words, English by default. Override any of them under `barChart` in `<LocaleProvider strings={{ barChart: { … } }}>`; the table is exported as `barChartStrings`.

- `noData`: No data
- `noDataInline`: no data
- `byCategory`: {series} by category
- `category`: {category}: {values}
- `seriesValue`: {series} {value}

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.