A Box Plot Series, also known as a Box-and-Whisker Plot, visually summarises a dataset's distribution through its median and quartiles.
Simple Box Plot Copy Link
import {
AgChartOptions,
AgCharts,
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
ContextMenuModule,
CrosshairModule,
LegendModule,
ModuleRegistry,
NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";
ModuleRegistry.registerModules([
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
CrosshairModule,
LegendModule,
NumberAxisModule,
ContextMenuModule,
]);
const options: AgChartOptions = {
title: {
text: "HR Analytics",
},
subtitle: {
text: "Salary Distribution by Department",
},
data: getData(),
series: [
{
type: "box-plot",
yName: "Employee Salaries",
xKey: "department",
minKey: "min",
q1Key: "q1",
medianKey: "median",
q3Key: "q3",
maxKey: "max",
},
],
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
export function getData() {
return [
{
department: "Sales",
min: 1052,
q1: 4465,
median: 5765,
q3: 8834,
max: 14852,
},
{
department: "R&D",
min: 1009,
q1: 2741,
median: 4377,
q3: 7725,
max: 14814,
},
{
department: "HR",
min: 1555,
q1: 2696,
median: 4071,
q3: 9756,
max: 19717,
},
];
}
To create a Box Plot Series, use the box-plot series type.
{
series: [
{
type: 'box-plot',
yName: 'Employee Salaries',
xKey: 'department',
minKey: 'min',
q1Key: 'q1',
medianKey: 'median',
q3Key: 'q3',
maxKey: 'max',
},
],
}In this configuration:
yNamespecifies the tooltip title.xKeysets the box plot's category.minKeymaps to the minimum value.q1Keymaps to the first quartile (Q1).medianKeymaps to the median.q3Keymaps to the third quartile (Q3).maxKeymaps to the maximum value.
Note the default orientation of a Box Plot is vertical.
Horizontal Box Plot Copy Link
import {
AgChartOptions,
AgCharts,
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
ContextMenuModule,
CrosshairModule,
LegendModule,
ModuleRegistry,
NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";
ModuleRegistry.registerModules([
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
CrosshairModule,
LegendModule,
NumberAxisModule,
ContextMenuModule,
]);
const options: AgChartOptions = {
title: {
text: "HR Analytics",
},
subtitle: {
text: "Salary Distribution by Role",
},
data: getData(),
series: [
{
type: "box-plot",
direction: "horizontal",
yName: "Employee Salaries",
xKey: "role",
xName: "Role",
minKey: "min",
minName: "Min",
q1Key: "q1",
q1Name: "Q1",
medianKey: "median",
medianName: "Median",
q3Key: "q3",
q3Name: "Q3",
maxKey: "max",
maxName: "Max",
},
],
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
export function getData() {
return [
{
role: "Sales Executive",
min: 4001,
q1: 5071,
median: 6232,
q3: 8620,
max: 13872,
},
{
role: "Research Scientist",
min: 1009,
q1: 2389,
median: 2889,
q3: 3904,
max: 5974,
},
{
role: "Manufacturing Director",
min: 4011,
q1: 5121,
median: 6474,
q3: 9547,
max: 13973,
},
{
role: "Manager",
min: 12504,
q1: 16437,
median: 17465,
q3: 19187,
max: 19999,
},
{
role: "Research Director",
min: 11031,
q1: 13499,
median: 16598,
q3: 19038,
max: 19973,
},
{
role: "Human Resources",
min: 1555,
q1: 2342,
median: 3195,
q3: 5985,
max: 10725,
},
];
}
To show a Horizontal Box Plot, set direction: 'horizontal'.
{
series: [
{
type: 'box-plot',
direction: 'horizontal',
xKey: 'department',
// ...
},
],
}Note that the xKey specifies the category values, regardless of series orientation.
Customisation Copy Link
import {
AgChartOptions,
AgCharts,
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
ContextMenuModule,
CrosshairModule,
LegendModule,
ModuleRegistry,
NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";
ModuleRegistry.registerModules([
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
CrosshairModule,
LegendModule,
NumberAxisModule,
ContextMenuModule,
]);
const options: AgChartOptions = {
title: {
text: "HR Analytics",
},
subtitle: {
text: "Salary Distribution by Role",
},
data: getData(),
series: [
{
type: "box-plot",
yName: "Employee Salaries",
xKey: "role",
xName: "Role",
minKey: "min",
minName: "Min",
q1Key: "q1",
q1Name: "Q1",
medianKey: "median",
medianName: "Median",
q3Key: "q3",
q3Name: "Q3",
maxKey: "max",
maxName: "Max",
fill: "#7fc3c3",
stroke: "#098a89",
strokeWidth: 2,
whisker: {
stroke: "#098a89",
strokeWidth: 3,
lineDash: [2, 1],
},
cap: {
lengthRatio: 0.8,
},
},
],
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
export function getData() {
return [
{
role: "Sales",
min: 4001,
q1: 5071,
median: 6232,
q3: 8620,
max: 13872,
},
{
role: "Research",
min: 1009,
q1: 2389,
median: 2889,
q3: 3904,
max: 5974,
},
{
role: "Manufacturing",
min: 4011,
q1: 5121,
median: 6474,
q3: 9547,
max: 13973,
},
{
role: "Manager",
min: 12504,
q1: 16437,
median: 17465,
q3: 19187,
max: 19999,
},
{
role: "HR",
min: 1555,
q1: 2342,
median: 3195,
q3: 5985,
max: 10725,
},
];
}
Box Plot whiskers and caps typically inherit series styles but can be individually customised. Here, the whisker and cap properties are used to customise whisker line styles and cap length.
{
series: [
{
type: 'box-plot',
// Other series options...
whisker: {
stroke: '#098a89',
strokeWidth: 3,
lineDash: [2, 1],
},
cap: {
lengthRatio: 0.8, // 80% of bar's width (default is 0.5)
},
},
],
} Box Plot With Outliers Copy Link
import {
AgChartOptions,
AgCharts,
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
ContextMenuModule,
CrosshairModule,
LegendModule,
ModuleRegistry,
NumberAxisModule,
ScatterSeriesModule,
} from "ag-charts-enterprise";
import { getBoxPlotData, getOutliersData } from "./data";
ModuleRegistry.registerModules([
AnimationModule,
BoxPlotSeriesModule,
CategoryAxisModule,
CrosshairModule,
LegendModule,
NumberAxisModule,
ScatterSeriesModule,
ContextMenuModule,
]);
const options: AgChartOptions = {
title: {
text: "HR Analytics",
},
subtitle: {
text: "Salary Distribution by Role",
},
series: [
{
data: getBoxPlotData(),
type: "box-plot",
yName: "Employee Salaries",
xKey: "role",
xName: "Role",
minKey: "min",
minName: "Min",
q1Key: "q1",
q1Name: "Q1",
medianKey: "median",
medianName: "Median",
q3Key: "q3",
q3Name: "Q3",
maxKey: "max",
maxName: "Max",
},
{
data: getOutliersData(),
type: "scatter",
xKey: "role",
xName: "Role",
yKey: "salary",
yName: "Data Outliers",
},
],
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
export function getBoxPlotData() {
return [
{
role: "Sales",
min: 4001,
q1: 5071,
median: 6232,
q3: 8620,
max: 13872,
outliers: [],
},
{
role: "Research",
min: 1009,
q1: 2389,
median: 2889,
q3: 3904,
max: 5974,
outliers: [6220, 6322, 6545, 6646, 6854, 6962, 9724],
},
{
role: "Manufacturing",
min: 4011,
q1: 5121,
median: 6474,
q3: 9547,
max: 13973,
outliers: [],
},
{
role: "Manager",
min: 12504,
q1: 16437,
median: 17465,
q3: 19187,
max: 19999,
outliers: [11244, 11557, 11631, 11849, 11878, 11904, 11916, 11996],
},
{
role: "HR",
min: 1555,
q1: 2342,
median: 3195,
q3: 5985,
max: 10725,
outliers: [],
},
];
}
export function getOutliersData() {
return getBoxPlotData().flatMap((item) =>
item.outliers.map((outlier) => ({
role: item.role,
salary: outlier,
})),
);
}
Box plots are commonly paired with outliers to offer a more comprehensive view of the data. This is easily achieved by combining a Box Plot Series with a Scatter Series, as shown below:
{
series: [
{
data: boxPlotData,
type: 'box-plot',
// ...
},
{
data: outliersData,
type: 'scatter',
// ...
},
],
} Box Plot Chart Examples Copy Link
See more Box Plot Chart examples in the AG Charts Gallery.
API Reference Copy Link
Properties available on the AgBoxPlotSeriesOptions interface.
- type required
'box-plot' - Configuration for the Box Plot Series.
- xKey required
DatumKey - The key used to retrieve x-values (categories) from the data.
- minKey required
DatumKey - The key to use to retrieve minimum values from the data.
- q1Key required
DatumKey - The key to use to retrieve lower quartile values from the data.
- medianKey required
DatumKey - The key to use to retrieve median values from the data.
- q3Key required
DatumKey - The key to use to retrieve upper quartile values from the data.
- maxKey required
DatumKey - The key to use to retrieve maximum values from the data.
- grouped
boolean - Whether to group together (adjacently) separate columns.
- legendItemName
string - Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together.
- direction
'horizontal' | 'vertical' - Bar rendering direction. __Note:__ This option affects the layout direction of X and Y data values.
- tooltip
AgSeriesTooltip - Series-specific tooltip configuration.
- styler
Styler - Function used to return formatting for entire series, based on the given parameters.
- itemStyler
Styler - Function used to return formatting for individual columns, based on the given parameters.
- highlight
AgMultiSeriesHighlightOptions - Configuration for highlighting when a series or legend item is hovered over.
- segmentation
AgSeriesSegmentation - Configuration for styling series as separate segments.
- width
PixelSize - Fixed width of each box in the series.
- widthRatio
Ratio - Ratio of the bandwidth (or specified width) to use for the width for each box in the series.
- showInMiniChart
boolean - Whether to include the series in the Mini Chart.
- cursor
string - The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
- context
ContextDefault - Context object to use in callbacks.
- selection
AgSelectionOptions - Configuration for data selection.
- nodeClickRange
InteractionRange - Range from a node that a click triggers the listener.
- showInLegend
boolean - Whether to include the series in the legend.
- listeners
AgSeriesListeners - A map of event names to event listeners.
- cornerRadius
PixelSize - Apply rounded corners to each bar.
- cap
AgBoxPlotCapOptions - Options to style chart's caps
- whisker
AgBoxPlotWhiskerOptions - Options to style chart's whiskers
- fill
AgColorType - The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill.
- fillOpacity
Opacity - The opacity of the fill colour.
- stroke
AgCssColorOrRef - The colour for the stroke.
- strokeWidth
PixelSize - The width of the stroke in pixels.
- strokeOpacity
Opacity - The opacity of the stroke colour.
- lineDash
PixelSize[] - An array specifying the length in pixels of alternating dashes and gaps.
- lineDashOffset
PixelSize - The initial offset of the dashed line in pixels.
- id
stringdefault: auto-generated value - Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
- data
DatumDefault[] - The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
- visible
boolean - Whether to display the series.
- xKeyAxis
stringdefault: 'x' - The key of the x-axis to which this series is bound.
- yKeyAxis
stringdefault: 'y' - The key of the y-axis to which this series is bound.
- xName
string - A descriptive label for x-values.
- minName
string - A human-readable description of minimum values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- q1Name
string - A human-readable description of lower quartile values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- medianName
string - A human-readable description of median values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- q3Name
string - A human-readable description of upper quartile values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- maxName
string - A human-readable description of maximum values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- yName
string - A descriptive label for y-values.
Properties available on the AgBoxPlotSeriesOptions interface.
- type required
'box-plot' - Configuration for the Box Plot Series.
- xKey required
DatumKey - The key used to retrieve x-values (categories) from the data.
- minKey required
DatumKey - The key to use to retrieve minimum values from the data.
- q1Key required
DatumKey - The key to use to retrieve lower quartile values from the data.
- medianKey required
DatumKey - The key to use to retrieve median values from the data.
- q3Key required
DatumKey - The key to use to retrieve upper quartile values from the data.
- maxKey required
DatumKey - The key to use to retrieve maximum values from the data.
- grouped
boolean - Whether to group together (adjacently) separate columns.
- legendItemName
string - Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together.
- direction
'horizontal' | 'vertical' - Bar rendering direction. __Note:__ This option affects the layout direction of X and Y data values.
- tooltip
AgSeriesTooltip - Series-specific tooltip configuration.
- styler
Styler - Function used to return formatting for entire series, based on the given parameters.
- itemStyler
Styler - Function used to return formatting for individual columns, based on the given parameters.
- highlight
AgMultiSeriesHighlightOptions - Configuration for highlighting when a series or legend item is hovered over.
- segmentation
AgSeriesSegmentation - Configuration for styling series as separate segments.
- width
PixelSize - Fixed width of each box in the series.
- widthRatio
Ratio - Ratio of the bandwidth (or specified width) to use for the width for each box in the series.
- showInMiniChart
boolean - Whether to include the series in the Mini Chart.
- cursor
string - The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
- context
ContextDefault - Context object to use in callbacks.
- selection
AgSelectionOptions - Configuration for data selection.
- nodeClickRange
InteractionRange - Range from a node that a click triggers the listener.
- showInLegend
boolean - Whether to include the series in the legend.
- listeners
AgSeriesListeners - A map of event names to event listeners.
- cornerRadius
PixelSize - Apply rounded corners to each bar.
- cap
AgBoxPlotCapOptions - Options to style chart's caps
- whisker
AgBoxPlotWhiskerOptions - Options to style chart's whiskers
- fill
AgColorType - The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill.
- fillOpacity
Opacity - The opacity of the fill colour.
- stroke
AgCssColorOrRef - The colour for the stroke.
- strokeWidth
PixelSize - The width of the stroke in pixels.
- strokeOpacity
Opacity - The opacity of the stroke colour.
- lineDash
PixelSize[] - An array specifying the length in pixels of alternating dashes and gaps.
- lineDashOffset
PixelSize - The initial offset of the dashed line in pixels.
- id
stringdefault: auto-generated value - Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
- data
DatumDefault[] - The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
- visible
boolean - Whether to display the series.
- xKeyAxis
stringdefault: 'x' - The key of the x-axis to which this series is bound.
- yKeyAxis
stringdefault: 'y' - The key of the y-axis to which this series is bound.
- xName
string - A descriptive label for x-values.
- minName
string - A human-readable description of minimum values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- q1Name
string - A human-readable description of lower quartile values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- medianName
string - A human-readable description of median values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- q3Name
string - A human-readable description of upper quartile values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- maxName
string - A human-readable description of maximum values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
- yName
string - A descriptive label for y-values.