# Histogram

The shape of one distribution.

- Group: Charts
- Import: `import { Histogram } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/histogram/
- Related: box-plot, bar-chart

## When to reach for it

A single distribution has to be understood — two clusters, a hard floor, a pile-up at a timeout. Several distributions side by side want a BoxPlot.

## Accessibility

- The shape is a property of the bin width, not only of the data: the same numbers cut into eight buckets and into eighty are two different pictures. The rule that drew it — Freedman–Diaconis by default — is named on the page.
- The x axis is numeric and every bar is drawn from its own two edges, so an uneven bucket is as wide as it really is rather than flattened into an equal slot.
- mode="density" corrects the trap uneven buckets create: under frequency a bucket twice as wide stands twice as tall at the same underlying rate.
- The hidden data table prints each bucket’s two edges and its count, which is the only exact reading a binned chart can offer.

## Histogram

The shape of one distribution — where the mass sits, how it leans, whether there is more than one hump in it. The form that answers what a `<BoxPlot>` structurally cannot: two clusters, a hard floor, a pile-up at a timeout value. Reach for the box plot when several distributions have to be compared side by side, and for this one when a single distribution has to be understood. **A histogram's shape is a property of its bin width, not only of its data.** The same numbers cut into eight buckets and into eighty are two different pictures, and a gap between two humps can be created or erased by moving a bin edge. That is not a defect to be fixed, it is what binning IS, and the defence is to say which rule drew the picture — the default here is Freedman–Diaconis — and to look at more than one width before believing a feature. Uneven buckets add a second trap: under `frequency` a bucket twice as wide stands twice as tall at the same underlying rate, which is what `mode="density"` exists to correct. Recharts earns its place here for the axes, the grid and the tooltip, but not for the bars: a bar chart's bars are positioned by CATEGORY and a histogram's are positioned and SIZED by a continuous measurement. So the x axis is numeric and each bar is drawn from its own two edges — which is what lets an uneven bucket be as wide as it really is instead of being flattened into an equal slot beside its neighbours.

### Props

- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a histogram has one distribution and as many bars as it has buckets.
- `values` — `number[]`. The raw observations, in any order. Binned for you by `bins`. Give this OR `data`, not both — `data` wins if both arrive.
- `data` — `HistogramBin[]`. Buckets that were counted somewhere else — by a database, by a sketch, by a metrics backend that only ever ships histograms. Uneven bucket widths are drawn at their real widths, which is the whole reason this takes edges rather than labels. Set `mode="density"` when they are uneven, or the wide buckets will read as tall ones.
- `bins` — `number | number[]`. How to cut `values` up: a number of equal-width bins, or the explicit edges. Defaults to Freedman–Diaconis (`2 × IQR × n^(-1/3)`), falling back to Sturges when the interquartile range is zero.
- `mode` — `HistogramMode` default `'frequency'`. What the bar heights mean. `frequency` is the count in each bucket and is what a reader assumes. `density` is `count / (n × bin width)`, so the total area is 1 — which is what makes two histograms of different sample sizes comparable, and what makes uneven buckets honest.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<Histogram.Bars>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats the measured values — bin edges, ticks, the tooltip's heading.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { Histogram } from '@misoto22/design/charts'

<Histogram
  title="Request duration"
  showTitle
  description="Binned by Freedman–Diaconis"
  values={samples}
>
  <Histogram.Grid />
  <Histogram.XAxis label="ms" />
  <Histogram.YAxis />
  <Histogram.Tooltip />
  <Histogram.Bars />
</Histogram>
```

## Example — bin width

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { Histogram } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={choice}
    onValueChange={(next) => next && setChoice(next as (typeof WIDTHS)[number])}
    aria-label="Bin count"
  >
    {WIDTHS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option === 'auto' ? 'auto' : `${option} bins`}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <Histogram
    title={`Request duration — ${choice === 'auto' ? 'Freedman–Diaconis' : `${choice} bins`}`}
    values={samples}
    bins={choice === 'auto' ? undefined : Number(choice)}
  >
    <Histogram.Grid />
    <Histogram.XAxis label="ms" />
    <Histogram.YAxis />
    <Histogram.Tooltip />
    <Histogram.Bars />
  </Histogram>
</div>
```

## Example — density

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { Histogram, type HistogramBin, type HistogramMode } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={mode}
    onValueChange={(next) => next && setMode(next as HistogramMode)}
    aria-label="Bar height"
  >
    {MODES.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <Histogram title={`Request duration — ${mode}`} data={buckets} mode={mode}>
    <Histogram.Grid />
    <Histogram.XAxis label="ms" />
    <Histogram.YAxis />
    <Histogram.Tooltip />
    <Histogram.Bars />
  </Histogram>
</div>
```