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
To create a Box Plot Series, use the box-plot
series type.
series: [
{
type: 'box-plot',
yName: 'Salary Range',
xKey: 'role',
minKey: 'min',
q1Key: 'q1',
medianKey: 'median',
q3Key: 'q3',
maxKey: 'max',
},
],
In this configuration:
yName
specifies the tooltip title.xKey
sets the box plot's category.minKey
maps to the minimum value.q1Key
maps to the first quartile (Q1).medianKey
maps to the median.q3Key
maps to the third quartile (Q3).maxKey
maps to the maximum value.
Note the default orientation of a Box Plot is vertical.
Horizontal Box Plot
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
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
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',
// ...
},
],
API Reference
Properties available on the AgBoxPlotSeriesOptions
interface.
Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together.
Bar rendering direction.
Note: This option affects the layout direction of X and Y data values.
Function used to return formatting for individual columns, based on the given parameters. If the current column is highlighted, the highlighted
property will be set to true
; make sure to check this if you want to differentiate between the highlighted and un-highlighted states.
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.
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
Configuration for marker and series highlighting when a series or legend item is hovered over.
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.
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.
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.
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.
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.