# Histogram

> A distribution against specification limits, with n, mean, standard deviation and Cpk stated in words.

Category: Charts · Atomic level: organism
Page: https://ui.dtheo.dev/docs/charts/histogram

## Install

```bash
npx dtheo@latest add histogram
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/histogram.json
```

Dependencies: d3-array, d3-scale. Registry dependencies: none.

## Exports

`Histogram`

## Use it for

- Test results and quality data against a spec
- Is this run unusual, or is the whole process off?

## Reach for something else

- A few categories: use Bar chart
- Two measures together: use Scatter chart

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `number[]` | – | Raw measurements, one per run or part. |
| `binWidth` | `number` | – | Bin width in the values’ unit. Defaults to the Freedman–Diaconis rule. |
| `lower` | `number` | – | Lower specification limit. Bins below it turn critical; Cpk uses it. |
| `upper` | `number` | – | Upper specification limit. Bins above it turn critical; Cpk uses it. |
| `marker` | `{ value: number; label: string }` | – | Call out one value, such as this run. |
| `normal` | `boolean` | `false` | Overlay the normal curve with the sample mean and standard deviation. |

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / right | Move to the next bin |
| Shift + arrow | Skip a tenth of the bins |
| Home / End | Jump to the first or last bin |
| Escape | Clear the readout |

## Accessibility

- Bins outside the limits turn critical and the readout says "out of spec".
- Cpk carries a word (capable, marginal, not capable) next to its number.

## Examples

### histogram

```tsx
import { Histogram } from '@/components/charts/histogram';
// Synthetic demo data: npx dtheo add lab-data, or pass your own.
import { OVERSHOOT_USL, runs } from '@/lib/lab-data';

const overshoot = runs.map((r) => r.overshoot);

export default function HistogramExample() {
  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex flex-col">
        <span className="text-headline">Overshoot across all runs</span>
        <span className="text-caption text-muted-foreground">
          RA-14 hip pitch · Bench 3 · since firmware 4.16
        </span>
      </div>
      <Histogram
        values={overshoot}
        domain={[0, 20]}
        binWidth={1}
        upper={OVERSHOOT_USL}
        target={5}
        marker={{ value: 17.6, label: 'R-0412' }}
        normal
        xLabel="Overshoot"
        unit="%"
        height={240}
        ariaLabel={`Overshoot of ${overshoot.length} runs: most sit between 3 and 8 %, and 12 runs exceed the 10 % limit. Cpk is 0.6, so the process is not capable at these gains.`}
      />
    </div>
  );
}
```

## Used in

- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
