# Box Plot (/docs/charts/components/box-plot)

Use a box plot to compare how values are spread across a few groups, like response times per page, when the median and range matter more than each value.

<Example caption="Hover a box, or focus the chart and press the arrow keys, to see its median.">
<Basic />

```tsx
"use client";

import { BoxPlotChart, type BoxPlotSummary, type SeriesConfig } from "@kind-ui/charts";

type Row = { page: string; summary: BoxPlotSummary | null };

const data: Row[] = [
  {
    page: "Search",
    summary: { lowerWhisker: 18, q1: 32, median: 44, q3: 61, upperWhisker: 84, outliers: [112] },
  },
  {
    page: "Checkout",
    summary: { lowerWhisker: 26, q1: 46, median: 68, q3: 88, upperWhisker: 126, outliers: [154] },
  },
  {
    page: "Profile",
    summary: { lowerWhisker: 12, q1: 22, median: 31, q3: 46, upperWhisker: 72, outliers: [98] },
  },
];

const config = {
  latency: { label: "Response time", color: "#733bff" },
} satisfies SeriesConfig;

export default function ResponseTimeBoxPlot() {
  return (
    <BoxPlotChart
      data={data}
      config={config}
      animate
      aria-label="Response times by page, in milliseconds"
    >
      <BoxPlotChart.Grid vertical={false} />
      <BoxPlotChart.XAxis dataKey="page" />
      <BoxPlotChart.YAxis width={40} domain={[0, 180]} />
      <BoxPlotChart.Series<Row> dataKey="summary" seriesKey="latency" barSize={32} />
      <BoxPlotChart.Tooltip
        formatter={(_value, _name, entry) => [`${entry.payload.summary.median} ms`, "Median"]}
      />
      <BoxPlotChart.Legend />
    </BoxPlotChart>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
BoxPlotChart
├── BoxPlotChart.Background
├── BoxPlotChart.Grid
├── BoxPlotChart.XAxis
├── BoxPlotChart.YAxis
├── BoxPlotChart.Series
│   └── BoxPlotChart.Mark
├── BoxPlotChart.Tooltip
├── BoxPlotChart.Legend
└── BoxPlotChart.Content
```

`BoxPlotChart` holds the data, the series config and the accessible name, and draws only the parts you add. `BoxPlotChart.Series` draws one box per row: the box spans `q1` to `q3`, the line across it marks the `median`, the whiskers reach `lowerWhisker` and `upperWhisker`, and each outlier is a circle. Its `seriesKey` picks the label and color in `config`. `BoxPlotChart.Mark` draws one box, for a custom `shape`. `BoxPlotChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Summaries [#summaries]

The chart draws statistics you've already computed; it doesn't pick a quartile method or decide what counts as an outlier. Give each row a `BoxPlotSummary`, and point the series' `dataKey` at it, or pass a function that builds one from the row:

```tsx
<BoxPlotChart.Series<Row>
  dataKey={(row) => ({ lowerWhisker: row.min, q1: row.p25, median: row.p50, q3: row.p75, upperWhisker: row.max })}
  seriesKey="latency"
/>
```

The values must be finite and in order, from `lowerWhisker` up to `upperWhisker`, and each outlier must lie outside the whiskers, or the chart throws. Equal values are fine: a summary where every value is the same draws a flat line. A `null` summary draws no box but keeps its category on the axis. Set the Y axis `domain` to include your outliers.

`validateBoxPlotSummary` runs the same checks on a summary, and `boxPlotExtent` returns its lowest and highest values, outliers included.

Set `material="clay"` or `"glow"` on the series for a finish; see [Materials](../guides/materials.mdx). To draw the boxes yourself, pass a `shape`; it gets the summary and its screen coordinates, and can render `BoxPlotChart.Mark`.

### Tooltip [#tooltip]

The default tooltip shows each box's full range. To show a statistic instead, pass a `formatter` that reads the summary from `entry.payload`, as the example does for the median, or pass your own `content` to show them all.

### Horizontal Boxes [#horizontal-boxes]

Set `layout="vertical"` for horizontal boxes, with the number scale on the X axis and the categories on the Y axis:

```tsx
<BoxPlotChart layout="vertical" {...props}>
  <BoxPlotChart.XAxis type="number" domain={[0, 180]} />
  <BoxPlotChart.YAxis type="category" dataKey="page" width={80} />
  <BoxPlotChart.Series<Row> dataKey="summary" seriesKey="latency" barSize={28} />
</BoxPlotChart>
```

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

Set `animate` to reveal the boxes when the chart mounts. When the reader prefers reduced motion, boxes appear at once. 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
<BoxPlotChart loading={isPending} loadingLabel="Loading response times" {...props}>
```

## API Reference [#api-reference]

### BoxPlotChart [#boxplotchart]

### BoxPlotChartOptions

| Prop                     | Type                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data?`                  | `ChartData<unknown> \| undefined`                                                                                                                                                                                                                    | The source data. Each element should be an object. The properties of each object represent the values of different data dimensions. Use the `dataKey` prop to specify which properties to use. |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show, when you control visibility.                                                                                                                                          |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show first, when the chart controls visibility.                                                                                                                             |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                              | Called with the next visible series keys when the legend hides or shows one.                                                                                                                   |
| `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"`                                                                                                                     |
| `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.                                                                                                         |

### BoxPlotChart.Series [#boxplotchartseries]

### BoxPlotSeriesOptions

| Prop             | Type                                                                                | Description                                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seriesKey`      | `string`                                                                            | The series' key in `config`, for its label, color and visibility. Required when `dataKey` is a function or a number. The series' key in `config`, for its label, color and visibility. Default: `dataKey` |
| `dataKey`        | `string \| ((row: Record<string, unknown>) => BoxPlotSummary \| null \| undefined)` | The row field that holds each `BoxPlotSummary`, or a function that returns it. `null` draws no box. Nested paths aren't read.                                                                             |
| `material?`      | `"clay" \| "glow" \| "plain"`                                                       | A finish for the boxes: `"clay"` or `"glow"`. An explicit `filter` replaces it. Default: `"plain"`                                                                                                        |
| `shape?`         | `((props: BoxPlotShapeProps) => ReactNode) \| undefined`                            | Draws each box yourself. Gets the summary, its screen coordinates and the Recharts bar props.                                                                                                             |
| `markProps?`     | `Omit<React.SVGProps<SVGGElement>, "children"> \| undefined`                        | Attributes, styles and handlers for each box's SVG group.                                                                                                                                                 |
| `outlierRadius?` | `number \| undefined`                                                               | The radius of each outlier circle, in pixels. Default: `3`                                                                                                                                                |

### BoxPlotSummary [#boxplotsummary]

### BoxPlotSummaryFields

| Prop           | Type                             | Description                                                  |
| -------------- | -------------------------------- | ------------------------------------------------------------ |
| `lowerWhisker` | `number`                         | The end of the lower whisker.                                |
| `q1`           | `number`                         | The first quartile, where the box starts.                    |
| `median`       | `number`                         | The median, drawn as a line across the box.                  |
| `q3`           | `number`                         | The third quartile, where the box ends.                      |
| `upperWhisker` | `number`                         | The end of the upper whisker.                                |
| `outliers?`    | `readonly number[] \| undefined` | Values drawn as circles. Each must lie outside the whiskers. |

<Caption>
`BoxPlotChart` and `BoxPlotChart.Series` also take Recharts' [BarChart](https://recharts.github.io/en-US/api/BarChart/) and [Bar](https://recharts.github.io/en-US/api/Bar/) props, like `layout` and `barSize`. The series doesn't take `stackId`, `radius`, `minPointSize`, `background` or `activeBar`.
</Caption>