Charts
BoxPlot
The spread of a measurement, per category.
When to reach for it
Examples
default
| name | Minimum | Lower quartile | Median | Upper quartile | Maximum | Outliers |
|---|---|---|---|---|---|---|
| Sydney | 182 | 195.75 | 207 | 219.25 | 236 | 1 |
| Singapore | 244 | 259 | 271.5 | 287.75 | 318 | 0 |
| Frankfurt | 310 | 326.5 | 341 | 358.75 | 379 | 1 |
| Oregon | 268 | 280.25 | 290.5 | 305.75 | 341 | 0 |
orientation
| name | Minimum | Lower quartile | Median | Upper quartile | Maximum | Outliers |
|---|---|---|---|---|---|---|
| ap-southeast-2 | 182 | 195.75 | 207 | 219.25 | 236 | 1 |
| ap-southeast-1 | 244 | 259 | 271.5 | 287.75 | 318 | 0 |
| eu-central-1 | 310 | 326.5 | 341 | 358.75 | 379 | 1 |
| us-west-2 | 268 | 280.25 | 290.5 | 305.75 | 341 | 0 |
notched
| name | Minimum | Lower quartile | Median | Upper quartile | Maximum | Outliers |
|---|---|---|---|---|---|---|
| Control | 180 | 214 | 236 | 262 | 318 | 0 |
| Variant A | 176 | 208 | 229 | 255 | 310 | 0 |
| Variant B | 184 | 226 | 258 | 291 | 356 | 0 |
Notes
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
| Prop | Type | Default | Description |
|---|---|---|---|
| childrenrequired | ReactNode | The composed parts — axes, grid, tooltip, and `<BoxPlot.Boxes>`. | |
| datarequired | BoxPlotDatum[] | One entry per category, as raw observations or as a summary. | |
| titlerequired | 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. | |
| chartProps | ComponentProps<typeof RechartsBarChart> | Escape hatch onto the raw Recharts chart element. | |
| className | string | Merged onto the figure, last, so a call site can size or space it. | |
| config | ChartConfig | 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. |
| description | ReactNode | A line under the title — the unit, the window, the caveat. | |
| 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. | |
| formatValue | (value: number) => string | defaultTick | Formats every number the chart prints — ticks, tooltip, table. |
| hideDataTable | boolean | false | Drops the hidden table view. Only correct when the page prints the data itself. |
| orientation | BoxPlotOrientation | 'vertical' | Which way the boxes run. Reach for `horizontal` when the category names are long enough to need rotating under a column. |
| showTitle | boolean | Prints the title above the plot instead of hiding it from sight. |
Types
export type BoxPlotOrientation = 'vertical' | 'horizontal'
export type BoxPlotDatum = BoxPlotSample | (BoxPlotSummary & { values?: never })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.