Box plot
Summarize a distribution with quartiles, whiskers, and outliers.
Chart ID: boxPlot. Independent import: @revolist/charts/box-plot.
Live example
Section titled “Live example”Loading chart…
Reading the chart
Section titled “Reading the chart”Compare medians, quartiles, whiskers and outliers from real samples or valid summaries. A category total alone cannot recover a distribution.
Data requirements
Section titled “Data requirements”Supply genuine source samples or valid distribution summaries through analyticalFrame.derived.distributions. A violin summary also needs density. Matrix aggregates alone do not define a distribution.
The roles below describe the chart's data contract. Generic category/value roles resolve from the dataset; explicitly bind specialized numeric roles as shown in the complete example.
| Data role | Field count |
|---|---|
category | 1 or more |
value | 1 or more |
series | 1 or more |
Download the complete sample data and settings (JSON). See Data & Configuration for mapping, null values, updates and lifecycle rules.
Create this chart
Section titled “Create this chart”Install the package using the installation guide, give the host an explicit height, and call createBoxPlotChart after the host mounts. This factory fixes the chart type to boxPlot.
<div id="chart" style="width: 100%; height: 450px;"></div>Complete runnable TypeScript example with sample data
import { createBoxPlotChart } from '@revolist/charts/box-plot';
const container = document.getElementById('chart')!;const chart = await createBoxPlotChart({ container, "dataset": { "revision": 0, "source": "client", "categories": [ { "id": "preview-category-0", "label": "12", "path": [ "12" ], "labels": [ "12" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-1", "label": "18", "path": [ "18" ], "labels": [ "18" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-2", "label": "23", "path": [ "23" ], "labels": [ "23" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-3", "label": "27", "path": [ "27" ], "labels": [ "27" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-4", "label": "31", "path": [ "31" ], "labels": [ "31" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-5", "label": "35", "path": [ "35" ], "labels": [ "35" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-6", "label": "42", "path": [ "42" ], "labels": [ "42" ], "depth": 1, "kind": "leaf" }, { "id": "preview-category-7", "label": "48", "path": [ "48" ], "labels": [ "48" ], "depth": 1, "kind": "leaf" } ], "series": [ { "id": "preview-series-0", "label": "Value", "columnPath": [ "Value" ], "labels": [ "Value" ], "kind": "leaf", "prop": "preview-0" } ], "values": [ [ 12 ], [ 18 ], [ 23 ], [ 27 ], [ 31 ], [ 35 ], [ 42 ], [ 48 ] ], "analyticalFrame": { "derived": { "distributions": [ { "kind": "samples", "categoryId": "preview-category-0", "seriesId": "preview-series-0", "samples": [ 8, 12, 14, 18, 19, 23, 27, 31, 48 ] }, { "kind": "samples", "categoryId": "preview-category-1", "seriesId": "preview-series-0", "samples": [ 10, 14, 16, 20, 21, 25, 29, 33, 50 ] }, { "kind": "samples", "categoryId": "preview-category-2", "seriesId": "preview-series-0", "samples": [ 12, 16, 18, 22, 23, 27, 31, 35, 52 ] }, { "kind": "samples", "categoryId": "preview-category-3", "seriesId": "preview-series-0", "samples": [ 14, 18, 20, 24, 25, 29, 33, 37, 54 ] }, { "kind": "samples", "categoryId": "preview-category-4", "seriesId": "preview-series-0", "samples": [ 16, 20, 22, 26, 27, 31, 35, 39, 56 ] }, { "kind": "samples", "categoryId": "preview-category-5", "seriesId": "preview-series-0", "samples": [ 18, 22, 24, 28, 29, 33, 37, 41, 58 ] }, { "kind": "samples", "categoryId": "preview-category-6", "seriesId": "preview-series-0", "samples": [ 20, 24, 26, 30, 31, 35, 39, 43, 60 ] }, { "kind": "samples", "categoryId": "preview-category-7", "seriesId": "preview-series-0", "samples": [ 22, 26, 28, 32, 33, 37, 41, 45, 62 ] } ] }, "fields": [ { "id": "pivot:category", "label": "pivot:category", "role": "dimension", "semanticType": "category" }, { "id": "pivot:series", "label": "pivot:series", "role": "dimension", "semanticType": "category" }, { "id": "preview-series-0", "label": "Value", "role": "measure", "semanticType": "number", "sourceField": "preview-0" } ], "observations": [ { "id": "[\"preview-category-0\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "12", "label": "12", "path": [ "12" ], "labels": [ "12" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 12 } }, { "id": "[\"preview-category-1\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "18", "label": "18", "path": [ "18" ], "labels": [ "18" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 18 } }, { "id": "[\"preview-category-2\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "23", "label": "23", "path": [ "23" ], "labels": [ "23" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 23 } }, { "id": "[\"preview-category-3\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "27", "label": "27", "path": [ "27" ], "labels": [ "27" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 27 } }, { "id": "[\"preview-category-4\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "31", "label": "31", "path": [ "31" ], "labels": [ "31" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 31 } }, { "id": "[\"preview-category-5\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "35", "label": "35", "path": [ "35" ], "labels": [ "35" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 35 } }, { "id": "[\"preview-category-6\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "42", "label": "42", "path": [ "42" ], "labels": [ "42" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 42 } }, { "id": "[\"preview-category-7\",\"preview-series-0\"]", "dimensions": { "pivot:category": { "value": "48", "label": "48", "path": [ "48" ], "labels": [ "48" ] }, "pivot:series": { "value": "Value", "label": "Value", "path": [ "Value" ], "labels": [ "Value" ] } }, "measures": { "preview-series-0": 48 } } ], "matrixCells": [ { "categoryId": "preview-category-0", "seriesId": "preview-series-0", "observationId": "[\"preview-category-0\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-1", "seriesId": "preview-series-0", "observationId": "[\"preview-category-1\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-2", "seriesId": "preview-series-0", "observationId": "[\"preview-category-2\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-3", "seriesId": "preview-series-0", "observationId": "[\"preview-category-3\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-4", "seriesId": "preview-series-0", "observationId": "[\"preview-category-4\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-5", "seriesId": "preview-series-0", "observationId": "[\"preview-category-5\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-6", "seriesId": "preview-series-0", "observationId": "[\"preview-category-6\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" }, { "categoryId": "preview-category-7", "seriesId": "preview-series-0", "observationId": "[\"preview-category-7\",\"preview-series-0\"]", "measureFieldId": "preview-series-0" } ] } }, "bindings": {}, "presentation": { "dataLabels": false }});
// When the host unmounts:// chart.destroy();Await updates before reading a snapshot or exporting. Call chart.destroy() when the host unmounts. See the live catalog to interact with this type.
Supported options
Section titled “Supported options”Set these fields in chartOptions. The option schema validates supported keys, ranges and choices; updating chartOptions replaces that authored object.
| Option | Default | Accepted values |
|---|---|---|
showGridLines | true | true or false |
markOpacity | 1 | 0.2 to 1; step 0.05 |
orientation | vertical | vertical, horizontal |
Configure primary, secondary and named numeric scales, bounds, reversal, formatting, ticks and measured axes through axes.y, axes.ySecondary, axes.yAxes and seriesOverrides[id].yAxis. Box/violin samples or summaries own their value projection; statistical intervals use bound matrix observations. Generic annotations follow that geometry. Primary and named category/time/numeric X axes, data/path mappings, independent windows, grouped labels, reversal, navigator, brushes and synchronization share the statistical projection. See statistical-axis options and limits.
Titles, legends, theme and labels belong to presentation or the corresponding top-level setting. Axis, color, navigation and interaction support depends on the selected chart; see Data & Configuration.
Compare multiple distributions
Section titled “Compare multiple distributions”Bind several distribution series to render side-by-side boxes in each category. Supply actual samples or valid precomputed summaries for each category/series pair; an aggregate measure alone cannot establish a distribution.
import { createChartDataset, createChartFactory } from '@revolist/charts/core';import { boxPlotChart } from '@revolist/charts/box-plot';
// Illustrative source samples for two plans within the North category.const standard = [12, 15, 18, 27];const premium = [20, 24, 28, 36];const mean = (values: number[]) => values.reduce((a, b) => a + b, 0) / values.length;const dataset = createChartDataset( [{ region: 'North', standard: mean(standard), premium: mean(premium) }], { category: { field: 'region' }, series: [{ field: 'standard' }, { field: 'premium' }], },);dataset.analyticalFrame!.derived = { distributions: [ { categoryId: dataset.categories[0].id, seriesId: 'standard', kind: 'samples', samples: standard, }, { categoryId: dataset.categories[0].id, seriesId: 'premium', kind: 'samples', samples: premium, }, ],};const createChart = createChartFactory([boxPlotChart]);const chart = await createChart({ container, dataset, chartType: 'boxPlot', bindings: { value: ['standard', 'premium'] },});Boxes retain stable series colors, and inspection provides sample and outlier
context. chartOptions: { orientation: 'horizontal' } changes orientation.
In Pivot, the automatic default remains one eligible measure; explicitly pass
several eligible seriesIds or bindings.value to compare distributions.
Pivot’s source-sample budgets still apply. Keep sample definitions and units
comparable across groups; never manufacture samples from summed values.
See Analysis for interpretation and limitations.
Value axes can be primary, secondary or named. Assign each selected series with seriesOverrides[id].yAxis; configure it in axes.y, axes.ySecondary or axes.yAxes. See statistical value-axis collections for grouping, source domains, orientation and Pivot controls.
Related charts
Section titled “Related charts”- Error interval — Compare a center value with its lower and upper bounds.
- Violin plot — Compare distribution shape and concentration across categories.
- Range and interval — Compare minimum, maximum, and mean values by category.
Charts overview · Installation · Data & Configuration
Assign independent category/time/numeric projections with axes.xAxes and seriesOverrides[id].xAxis. Both primary and named X axes support data maps or path level selection. See named statistical X axes for windows, interval grouping and physical placement.