# BoxPlot

The spread of a measurement, per category.

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

## When to reach for it

How variable is this, across six things at once. When the shape of ONE distribution is the question it wants a Histogram; when there are few enough observations to draw them all, a ScatterChart.

## Accessibility

- A box is five numbers, and five numbers cannot tell one hump from two. A bimodal distribution draws exactly the same box as a smooth one centred in the same place — the component says so in its own description rather than in a footnote.
- It also hides sample size: a box over six points and a box over six thousand are drawn identically. Carry count, and turn on notched whenever medians are being compared.
- Raw values are summarised with Tukey’s fences, which is stated on the page rather than assumed — a different fence rule draws different outliers from the same data.
- The hidden data table carries all five numbers per category, so the figure is readable without seeing the glyph.

## BoxPlot

The spread of a measurement, per category — median, middle half, reach, and the points that sit outside it. The form to reach for when the question is "how variable is this", and the one that answers it in a tenth of the ink a histogram per category would take. Six response-time distributions fit across one screen as six boxes; as six histograms they do not fit at all. **What a box plot hides is multimodality.** A box is five numbers, and five numbers cannot tell a single hump from two. A bimodal distribution — a fast cache path and a slow database path, two cohorts inside one average — draws exactly the same box as a smooth one centred in the same place, and the reader has no way to tell from the picture that the middle of the box is a value almost nothing takes. It also hides sample size: a box over six points and a box over six thousand are drawn identically, which is why `count` is worth carrying and why a notch, which does read `count`, is worth turning on when medians are being compared. When the SHAPE of one distribution is the question, reach for `<Histogram>`; when there are few enough observations to draw them all, reach for `<ScatterChart>` and plot the points. Recharts earns its place here: the boxes need a shared value axis with real ticks, a category axis, a grid and a tooltip, which is most of a cartesian chart. What it does not have is a box mark, so each box is drawn as a custom shape over a range bar — the bar supplies the category band and the scale, and the glyph inside it is ours.

### Props

- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a box plot has one measurement and as many categories as it has boxes.
- `data` (required) — `BoxPlotDatum[]`. One entry per category, as raw observations or as a summary.
- `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 `<BoxPlot.Boxes>`.
- `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.
- `orientation` — `BoxPlotOrientation` default `'vertical'`. Which way the boxes run. Reach for `horizontal` when the category names are long enough to need rotating under a column.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints — ticks, tooltip, table.
- `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 { BoxPlot } from '@misoto22/design/charts'

<BoxPlot
  title="Response time by region"
  showTitle
  description="One box per edge location, 24 hours"
  data={data}
>
  <BoxPlot.Grid />
  <BoxPlot.XAxis />
  <BoxPlot.YAxis label="ms" />
  <BoxPlot.Tooltip />
  <BoxPlot.Boxes />
</BoxPlot>
```

## Example — orientation

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { BoxPlot, type BoxPlotOrientation } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={orientation}
    onValueChange={(next) => next && setOrientation(next as BoxPlotOrientation)}
    aria-label="Orientation"
  >
    {ORIENTATIONS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <BoxPlot title="Response time by region" data={data} orientation={orientation}>
    <BoxPlot.Grid />
    <BoxPlot.XAxis />
    <BoxPlot.YAxis />
    <BoxPlot.Tooltip />
    <BoxPlot.Boxes />
  </BoxPlot>
</div>
```

## Example — notched

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

<BoxPlot
  title="Checkout latency by variant"
  showTitle
  description="Notch width falls with the square root of the sample"
  data={data}
>
  <BoxPlot.Grid />
  <BoxPlot.XAxis />
  <BoxPlot.YAxis label="ms" />
  <BoxPlot.Tooltip />
  <BoxPlot.Boxes notch />
</BoxPlot>
```