Skip to Content
kindui

Box Plot

Compare distributions with quartiles, whiskers and outliers.

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.

Hover a box, or focus the chart and press the arrow keys, to see its median.

Installation

npx shadcn@latest add @kind-ui/box-plot-chart

Composition

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

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:

<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. To draw the boxes yourself, pass a shape; it gets the summary and its screen coordinates, and can render BoxPlotChart.Mark.

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

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

<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

Set animate to reveal the boxes when the chart mounts. When the reader prefers reduced motion, boxes appear at once. See Motion.

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):

<BoxPlotChart loading={isPending} loadingLabel="Loading response times" {...props}>

API Reference

BoxPlotChart

Prop

Type

BoxPlotChart.Series

Prop

Type

BoxPlotSummary

Prop

Type

BoxPlotChart and BoxPlotChart.Series also take Recharts' BarChart and Bar props, like layout and barSize. The series doesn't take stackId, radius, minPointSize, background or activeBar.