# Histogram (/docs/charts/components/histogram)

Use a histogram to show the shape of a set of measurements, like response times, by counting how many fall into each interval.

<Example caption="Hover a bar, or focus the chart and press the arrow keys, to see how many requests fall in that interval.">
<Basic />

```tsx
"use client";

import { binHistogram, HistogramChart, type SeriesConfig } from "@kind-ui/charts";

const responseTimes = [
  12, 18, 23, 25, 27, 30, 31, 32, 34, 35, 36, 38, 40, 42, 43, 45, 47, 49, 50, 52, 55, 58, 60, 63,
  66, 70, 74, 80, 88, 95, 100, 110, 125, 150, 180, 200,
];

const { bins } = binHistogram(responseTimes, [0, 40, 80, 120, 160, 200]);

const config = {
  count: { label: "Requests", color: "#733bff" },
} satisfies SeriesConfig;

export default function ResponseTimeHistogram() {
  return (
    <HistogramChart
      bins={bins}
      measure="count"
      config={config}
      animate
      margin={{ right: 16 }}
      aria-label="Checkout response times, requests per 40 ms interval"
    >
      <HistogramChart.Grid vertical={false} />
      <HistogramChart.XAxis ticks={[0, 40, 80, 120, 160, 200]} tickFormatter={(ms) => `${ms} ms`} />
      <HistogramChart.YAxis width={40} allowDecimals={false} />
      <HistogramChart.Series />
      <HistogramChart.Tooltip
        labelFormatter={(_label, [entry]) => `${entry?.payload.lower}–${entry?.payload.upper} ms`}
      />
    </HistogramChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/histogram-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
HistogramChart
├── HistogramChart.Background
├── HistogramChart.Grid
├── HistogramChart.XAxis
├── HistogramChart.YAxis
├── HistogramChart.Series
├── HistogramChart.Tooltip
├── HistogramChart.Legend
└── HistogramChart.Content
```

`HistogramChart` holds the bins, the series config and the accessible name, and draws only the parts you add. It owns the scales: the X axis spans the first bin's `lower` to the last bin's `upper`, and the Y axis starts at zero. Add one `HistogramChart.Series`; its label and color come from the `count` entry in `config`. `HistogramChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Bins [#bins]

Pass `binHistogram` your raw values and the interval edges, in increasing order, and give its `bins` to the chart. Each bin includes its lower edge, and the last bin also includes its upper edge, so a value on an interior edge counts in the bin to its right:

```tsx
const { bins, missing, outOfRange } = binHistogram(responseTimes, [0, 40, 80, 120, 160, 200]);
```

`null` and `undefined` values count as `missing`, `NaN` and infinities as `nonfinite`, and values outside the edges as `outOfRange`; none of them get a bar. Edges that aren't finite and strictly increasing throw. You can also pass bins you've counted yourself, as `{ lower, upper, count }` objects. They may leave gaps but can't overlap.

### Count and Density [#count-and-density]

Set `measure="count"` to make each bar's height its count. When bins differ in width, set `measure="density"` instead: each bar's height becomes its share of the total per unit of width, so its area, not its height, is its share and wide bins don't look bigger than they are:

```tsx
const { bins } = binHistogram(responseTimes, [0, 25, 50, 100, 200]);

<HistogramChart bins={bins} measure="density" {...props}>
```

Set `material="clay"` or `"glow"` on the series for a finish; see [Materials](../guides/materials.mdx).

### Axes [#axes]

`HistogramChart.XAxis` and `HistogramChart.YAxis` take Recharts' tick and label props, like `ticks`, `tickFormatter` and `label`. Their `dataKey`, `type`, `domain` and `scale` belong to the chart.

### Motion and Loading [#motion-and-loading]

Set `animate` to grow the bars from zero when the chart mounts. When the reader prefers reduced motion, bars appear without growing. See [Motion](../guides/motion.mdx).

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder, and screen readers hear `loadingLabel` ("Loading chart" by default):

```tsx
<HistogramChart loading={isPending} loadingLabel="Loading response times" {...props}>
```

## API Reference [#api-reference]

### HistogramChart [#histogramchart]

### HistogramChartOptions

| Prop               | Type                                                                                                                                                                                                                                                 | Description                                                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `config`           | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                                  |
| `emphasis?`        | `"auto" \| "none"`                                                                                                                                                                                                                                   | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"`                                           |
| `interaction?`     | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                                   |
| `aria-label?`      | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                              |
| `aria-labelledby?` | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                                     |
| `legendPosition?`  | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                                       |
| `frameProps?`      | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                                    |
| `animate?`         | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                              | Grows the bars from zero on mount. Pass options to change the duration or easing. Reduced motion skips it. Default: `false`               |
| `loading?`         | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                                   |
| `loadingLabel?`    | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                |
| `bins`             | `readonly Readonly<{ lower: number; upper: number; count: number; }>[]`                                                                                                                                                                              | The intervals to draw, in order, each with `lower`, `upper` and `count`. Use `binHistogram` to make them.                                 |
| `measure`          | `"count" \| "density"`                                                                                                                                                                                                                               | What the bar height shows: `"count"`, or `"density"` so each bar's area is its share of the total. Use density when bins differ in width. |

### HistogramChart.Series [#histogramchartseries]

### HistogramSeriesOptions

| Prop         | Type                                                          | Description                                                                                               |
| ------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `seriesKey?` | `string \| undefined`                                         | The series' key in `config`, for its label, color and visibility. Default: `"count"`                      |
| `material?`  | `"clay" \| "glow" \| "plain"`                                 | A finish for the bars: `"clay"` or `"glow"`. A custom `shape` or `filter` replaces it. Default: `"plain"` |
| `shape?`     | `((props: HistogramShapeProps) => ReactElement) \| undefined` | Draws each bar yourself. Gets the Recharts bar props, sized to the bin, and the `bin`.                    |

<Caption>
`HistogramChart` also takes Recharts' [BarChart](https://recharts.github.io/en-US/api/BarChart/) props like `margin`, but not `data`, `layout` or bar spacing, which come from the bins.
</Caption>