import { BoxPlot } from "semiotic"
BoxPlot visualizes statistical distributions using box-and-whisker diagrams. Each box shows the median, first and third quartiles, and whiskers extending to the min and max values. Pass raw data points and the component computes the statistics automatically, with hover interactions that reveal quartile details.
Quick Start
A box plot requires just data — provide multiple data points per category and the component computes quartiles automatically.
import { BoxPlot } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { category: "Morning", value: 62 }, { category: "Morning", value: 58 }, { category: "Morning", value: 71 }, // ...multiple points per category { category: "Afternoon", value: 78 }, { category: "Afternoon", value: 85 }, // ...more data points ], /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", /* --- Customize --- */ categoryLabel: "Time of Day", valueLabel: "Response Time (ms)" } export default () => { return <BoxPlot {...frameProps} /> }
Examples
Horizontal Box Plot
Set orientation to "horizontal" for horizontal box-and-whisker diagrams.
import { BoxPlot } from "semiotic" const frameProps = { /* --- Data --- */ data: responseTimeData, /* --- Layout --- */ orientation: "horizontal", /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", /* --- Customize --- */ categoryLabel: "Time of Day", valueLabel: "Response Time (ms)" } export default () => { return <BoxPlot {...frameProps} /> }
Colored by Category
Use colorBy to give each box a distinct color based on a data field.
import { BoxPlot } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { category: "Region A", value: 120, zone: "Urban" }, { category: "Region A", value: 135, zone: "Urban" }, // ...data with zone field for coloring ], /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", /* --- Customize --- */ colorBy: "zone", categoryLabel: "Region", valueLabel: "Latency (ms)" } export default () => { return <BoxPlot {...frameProps} /> }
Without Outliers
Set showOutliers to false to hide outlier points beyond the whiskers.
import { BoxPlot } from "semiotic" const frameProps = { /* --- Data --- */ data: responseTimeData, /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", showOutliers: false, /* --- Customize --- */ showGrid: true, categoryLabel: "Time of Day", valueLabel: "Response Time (ms)" } export default () => { return <BoxPlot {...frameProps} /> }
Props
| Prop | Type | Required | Default | Description |
|---|
data | array | Yes | — | Array of data points. Multiple points per category are used to compute quartiles. |
categoryAccessor | string | function | — | "category" | Field name or function to access category values. |
valueAccessor | string | function | — | "value" | Field name or function to access numeric values. |
orientation | "vertical" | "horizontal" | — | "vertical" | Chart orientation. |
categoryLabel | string | — | — | Label for the category axis. |
valueLabel | string | — | — | Label for the value axis. |
valueFormat | function | — | — | Format function for value axis tick labels. |
colorBy | string | function | — | — | Field name or function to determine box color. |
colorScheme | string | array | — | "category10" | Color scheme name or custom colors array. |
showOutliers | boolean | — | true | Show outlier points beyond the whiskers. |
outlierRadius | number | — | 3 | Radius for outlier points. |
categoryPadding | number | — | 20 | Padding between categories in pixels. |
enableHover | boolean | — | true | Enable hover annotations showing quartile statistics. |
showGrid | boolean | — | false | Show background grid lines. |
showLegend | boolean | — | true (when colorBy set) | Show a legend. Defaults to true when colorBy is specified. |
tooltip | object | function | — | — | Tooltip configuration or render function. |
width | number | — | 600 | Chart width in pixels. |
height | number | — | 400 | Chart height in pixels. |
margin | object | — | { top: 50, bottom: 60, left: 70, right: 40 } | Margin around the chart area. |
title | string | — | — | Chart title displayed at the top. |
frameProps | object | — | — | Additional StreamOrdinalFrame props for advanced customization. Escape hatch to the full Frame API. |
Graduating to the Frame
When you need more control — custom summary rendering, overlaid swarm points, annotations — graduate toStreamOrdinalFrame directly. EveryBoxPlot is just a configured StreamOrdinalFrameunder the hood.
Chart (simple)
JSX
import { BoxPlot } from "semiotic" <BoxPlot data={responseTimeData} categoryAccessor="category" valueAccessor="value" showOutliers={true} categoryLabel="Time of Day" valueLabel="Response Time (ms)" />
Frame (full control)
JSX
import { StreamOrdinalFrame } from "semiotic" <StreamOrdinalFrame data={responseTimeData} oAccessor="category" rAccessor="value" summaryType={{ type: "boxplot", outliers: true }} summaryStyle={d => ({ fill: "#6366f1", stroke: "#6366f1", fillOpacity: 0.8 })} oPadding={20} axes={[ { orient: "left", label: "Response Time (ms)" }, { orient: "bottom", label: "Time of Day" } ]} summaryHoverAnnotation={true} size={[600, 400]} margin={{ top: 50, bottom: 60, left: 70, right: 40 }} />
The frameProps prop on BoxPlot lets you pass any StreamOrdinalFrame prop without fully graduating:
JSX
// Use frameProps as an escape hatch <BoxPlot data={responseTimeData} categoryAccessor="category" valueAccessor="value" frameProps={{ // Overlay individual points on the box plot type: "swarm", style: { fill: "#333", r: 2, fillOpacity: 0.4 }, annotations: [ { type: "or", category: "Afternoon", label: "Peak hours" } ] }} />
- SwarmPlot — show every individual data point as non-overlapping circles
- BarChart — for aggregated category comparisons
- StreamOrdinalFrame — the underlying Frame with full control over every rendering detail
- Annotations — adding callouts, highlights, and notes to any visualization
- Tooltips — custom tooltip content and positioning