||

Box Plot

Documentation Index

Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.

A composable box-and-whisker chart for comparing distributions, medians, and spread.

githubdocapi
Basic Box Plot

Overview

Use a box plot to compare the shape of several distributions without drawing every observation. Each box shows the first quartile, median, and third quartile; the whiskers show the minimum and maximum values supplied in the five-number summary.

The default variant uses a quiet translucent fill. Choose the blocks variant when stronger quartile bands make the distribution easier to scan.

Anatomy

BoxPlot owns the rows, category key, loading state, and selection. Add one Box per five-number-summary field, then compose optional Grid, XAxis, YAxis, Legend, and Tooltip parts.

Accessibility

Canvas charts need a meaningful text alternative. Provide an ariaLabel that explains the measure and categories, keep the tooltip enabled for exact values, and pair the chart with a table or written summary when the distribution is essential to the task. Do not rely on fill color alone to distinguish series.

Installation
npm install honestui

Usage

Each box value is an ordered tuple of [minimum, firstQuartile, median, thirdQuartile, maximum].

import { BoxPlot, type BoxPlotValue, type ChartConfig } from "honestui/charts";
const data: { region: string; latency: BoxPlotValue }[] = [
  { region: "North America", latency: [42, 58, 71, 86, 119] },
  { region: "Europe", latency: [38, 52, 66, 79, 108] },
];

<BoxPlot data={data} config={chartConfig} xDataKey="region">
  <BoxPlot.Grid />
  <BoxPlot.XAxis />
  <BoxPlot.YAxis />
  <BoxPlot.Legend />
  <BoxPlot.Tooltip />
  <BoxPlot.Box dataKey="latency" variant="default" />
</BoxPlot>

ECharts renders to a <canvas>, so the compound children are declarative configuration rather than live DOM nodes. Colors come from the same theme-aware ChartConfig used by the other Honest UI charts.

Blocks Variant

variant='blocks'

The blocks variant draws hard color bands inside each box. Give the series multiple colors in ChartConfig to control the bands, or provide one color and the chart will derive four opacity levels automatically.

Loading State

isLoading='true'

Pass isLoading to preserve the chart dimensions with neutral placeholder boxes and the shared loading treatment.

API Reference
BoxPlot
PropTypeDefaultDescription
data*TData[]–

Rows containing a category and one or more five-number-summary tuples.

config*ChartConfig–

Defines theme-aware labels and colors for each Box data key.

xDataKey*keyof TData & string–

The categorical field shown on the horizontal axis.

childrenReactNode–

The composed Grid, XAxis, YAxis, Legend, Tooltip, and Box parts.

classNamestring–

Additional classes for the chart container. Give the chart an explicit height.

animationbooleantrue

Enables the intro animation. Reduced-motion preferences disable it automatically.

defaultSelectedDataKeystring | nullnull

Series selected on first render.

onSelectionChange(key: string | null) => void–

Fires when a clickable box or legend item changes the selected series.

isLoadingbooleanfalse

Replaces the data with neutral placeholder boxes and a progress label.

loadingBoxesnumber6

Number of placeholder categories in the loading state.

ariaLabelstring–

Accessible name for the canvas chart. A descriptive label is generated when omitted.

chartOptionsRecord<string, unknown>–

Escape hatch merged over the generated ECharts option object.

Box
PropTypeDefaultDescription
dataKey*string–

Field containing [minimum, Q1, median, Q3, maximum]. The same key should exist in config.

variantdefault|blocks"default"

Uses a translucent continuous fill or discrete color bands.

boxWidthnumber | string | [number | string, number | string]–

Fixed width or ECharts minimum/maximum width range for each box.

isClickablebooleanfalse

Enables selection from the rendered series.

XAxis / YAxis
PropTypeDefaultDescription
tickFormatter(value, index) => string–

Formats category or numeric tick labels.

labelstring–

Axis title.

hideDotsbooleanfalse

Hides the small axis tick marks.

minnumber–

YAxis only. Sets the lower numeric bound.

maxnumber–

YAxis only. Sets the upper numeric bound.

Tooltip
PropTypeDefaultDescription
variantdefault|frosted-glass"default"

Tooltip surface treatment.

roundnesssm|md|lg|xl"lg"

Tooltip corner radius.

positionfixed|variable"variable"

Pins the tooltip to the top or lets it follow the active box.

valueFormatter(value: number) => string–

Formats all five values shown in the tooltip.

defaultIndexnumber–

Opens the tooltip on a category after mount.

Legend
PropTypeDefaultDescription
variantLegendVariant"rounded-square"

Indicator shape shared with the other chart legends.

alignleft|center|right"center"

Horizontal legend alignment.

verticalAligntop|middle|bottom"bottom"

Places the legend above, beside, or below the plot area.

isClickablebooleanfalse

Lets legend items select and isolate a series.