A Range Bar Series uses vertical or horizontal bars to show the range between high and low values in data. This series type is commonly used to assess data stability or variability.
Simple Range Bar
The Range Bar Series is created using the range-bar
series type.
series: [
{
type: 'range-bar',
xKey: 'department',
yLowKey: 'low',
yHighKey: 'high',
},
],
The yLowKey
and yHighKey
are used to retrieve the range of values for the Y axis.
Multiple Range Bar Series
Multiple Range Bar Series can be combined into a single chart.
series: [
{
type: 'range-bar',
xKey: 'date',
yLowKey: 'start',
yHighKey: 'gain',
xName: 'Month',
yLowName: 'Start',
yHighName: 'End',
yName: 'Gained',
},
{
type: 'range-bar',
xKey: 'date',
yLowKey: 'loss',
yHighKey: 'gain',
xName: 'Month',
yLowName: 'End',
yHighName: 'Start',
yName: 'Lost',
},
],
In this configuration:
yName
is used to control the text displayed in the legend.yLowName
,yHighName
andxName
are used to control the text displayed in the tooltip.
Missing Data
The series handles missing or invalid data based on the presence or validity of xKey
, yLowKey
and yHighKey
values in the data object.
When the axes types are continuous ('number'
, 'time'
or 'log'
), the yLowKey
, yHighKey
and xKey
values in the data object are considered invalid if they are:
+/-Infinity
null
undefined
NaN
Data entries with invalid yLowKey
, yHighKey
and xKey
values will result in gaps in the series.
Customisation
Labels
Series labels can be enabled using the label
options.
series: [
{
// ...
label: {
padding: 10,
formatter: ({ itemId, value }) => {
return `£${value.toFixed(0)}K ${itemId === 'low' ? '↓' : '↑'}`;
},
},
},
],
In this configuration:
- The
yHighKey
andyLowKey
values for each data point are presented as labels via thelabel
options. - The
label.formatter
function uses theitemId
from the params object to distinguish whether the label is alow
orhigh
value.
Corner Radius
The corner radius can be customised with the cornerRadius
property.
series: [
{
// ...
cornerRadius: 10,
},
],
Horizontal Range Bar
To create a Horizontal Range Bar Series, set direction: 'horizontal'
.
series: [
{
type: 'range-bar',
direction: 'horizontal',
xKey: 'department',
yLowKey: 'low',
yHighKey: 'high',
},
],
When the direction
is 'horizontal'
the xKey
will determine categories on the y-axis, while the yLowKey
and yHighKey
will be used to provide numerical values along the x-axis.
API Reference
Properties available on the AgRangeBarSeriesOptions
interface.
A human-readable description of the x-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 the y-low-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 the y-high-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 the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
Bar rendering direction.
Note: This option affects the layout direction of X and Y data values.
Function used to return formatting for individual RangeBar series item cells, based on the given parameters. If the current cell 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.