BoxPlot
Summarizes the spread of raw observations per category: quartiles, median, whiskers, and outliers.
stable
Quick Preview
Asking prices by neighbourhood
Active listings · ₦m
Usage
import { BoxPlot } from "@giddaa-housing/ui/box-plot";
<BoxPlot
data={[
{ area: "Lekki", price: 85 },
{ area: "Lekki", price: 104 },
{ area: "Yaba", price: 42 },
{ area: "Yaba", price: 55 },
]}
categoryKey="area"
valueKey="price"
formatValue={(value) => `₦${value}m`}
ariaLabel="Spread of asking prices by neighbourhood"
/>Pass raw observations, one row per observation. Each category is summarized with
Tukey rules: the box spans Q1–Q3, the line is the median, and whiskers reach the
furthest observations within 1.5 × IQR. Points beyond are outlier dots with their
own tooltip. outliers={false} stretches whiskers to the minimum and maximum
instead. Categories appear in first-seen order unless categories sets it.
Examples
Default
Asking prices by neighbourhood
Active listings · ₦m
Horizontal, ordered categories
orientation="horizontal" suits long category names; categories fixes the
order and drops observations in other categories.
Days on market
Sold properties · last 12 months
Props
| Prop/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | Raw observations, one row per observation. |
categoryKey | string or number field of T | required | Group of each observation; rows without one are omitted. |
valueKey | numeric field of T | required | Value summarized per group; missing values are omitted. |
ariaLabel | string | required | Accessible chart name. |
categories | (string | number)[] | first-seen order | Explicit order; other categories are omitted. |
orientation | "vertical" | "horizontal" | "vertical" | Box direction. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Plot height and type. |
color | CSS color | chart-1 | Box, median, and outlier color. |
colorByCategory | boolean | false | A palette slot per category instead of one color. |
outliers | boolean | true | Outlier dots beyond 1.5 × IQR; false spans whiskers to min and max. |
tooltip | boolean | true | Hover and keyboard tooltip with the five-number summary. |
grid | boolean | true | Value grid lines. |
valueDomain | [number, number] | fitted to the observations | Fixed value-axis extent. |
valueTicks | number[] | rounded | Exact value-axis ticks. |
formatValue | (value: number) => string | grouped number | Value axis and every tooltip value. |
formatCategory | (value: string | number) => string | String | Category labels. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid observations exist. |
| Chart host props | see Chart | - | height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
createBoxPlotDefinition(options) | function | - | Same options; returns an extensible TanStack definition. |
BoxPlotSummary, BoxPlotOutlier, BoxPlotDatum, BoxPlotDefinition | types | - | Exported for typed builders. |
Accessibility
- Provide a meaningful
ariaLabel; focus the chart and use arrow keys to move between boxes and outliers. - Box plots assume a statistical reader; say what the box and whiskers mean in the description for a general audience.
- Show the sample size per category nearby when groups are small; a box from five points reads as more certain than it is.