Charts
Histogram
The shape of one distribution.
When to reach for it
Examples
default
| label | Count |
|---|---|
| 62 – 103 | 37 |
| 103 – 144 | 6 |
| 144 – 185 | 22 |
| 185 – 226 | 5 |
| 226 – 267 | 3 |
| 267 – 308 | 2 |
bin width
| label | Count |
|---|---|
| 62 – 103 | 37 |
| 103 – 144 | 6 |
| 144 – 185 | 22 |
| 185 – 226 | 5 |
| 226 – 267 | 3 |
| 267 – 308 | 2 |
density
| label | Count |
|---|---|
| 0 – 10 | 480 |
| 10 – 25 | 610 |
| 25 – 50 | 540 |
| 50 – 100 | 420 |
| 100 – 250 | 310 |
| 250 – 500 | 120 |
| 500 – 1,000 | 40 |
Notes
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
| Prop | Type | Default | Description |
|---|---|---|---|
| childrenrequired | ReactNode | The composed parts — axes, grid, tooltip, and `<Histogram.Bars>`. | |
| 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. | |
| 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. | |
| 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 histogram has one distribution and as many bars as it has buckets. |
| 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. | |
| 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 the measured values — bin edges, ticks, the tooltip's heading. |
| hideDataTable | boolean | false | Drops the hidden table view. Only correct when the page prints the data itself. |
| mode | HistogramMode | '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. |
| showTitle | boolean | Prints the title above the plot instead of hiding it from sight. | |
| values | number[] | The raw observations, in any order. Binned for you by `bins`. Give this OR `data`, not both — `data` wins if both arrive. |
Types
export type HistogramMode = 'frequency' | 'density'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.