A Waterfall Series shows the cumulative effect of sequential positive or negative data values. It utilises rising and falling bars to create a cascading waterfall effect.
Simple Waterfall
The Waterfall Series is designed to display a single series and is created using the waterfall
series type.
series: [
{
type: 'waterfall',
xKey: 'financials',
yKey: 'amount',
},
],
The xKey
defines categories for the Category Axis, and the yKey
supplies numerical values for the Number Axis.
Legend toggling is disabled in Waterfall Series to avoid misleading or incorrect data representation.
Total / Subtotal Values
Adding Total and Subtotal values at specific points in a Waterfall Series can make the data easier to interpret. These values are automatically calculated based on the following criteria:
- Total: Accumulates all values from the starting point (zero) up to the current point.
- Subtotal: Begins at the last Total or Subtotal and sums up to the current point.
Total and Subtotal values are added to the totals
array within the series
options object.
series: [
{
type: 'waterfall',
xKey: 'financials',
yKey: 'amount',
totals: [
{ totalType: 'subtotal', index: 4, axisLabel: 'Total Revenue' },
{ totalType: 'subtotal', index: 9, axisLabel: 'Total Expenditure' },
{ totalType: 'total', index: 9, axisLabel: 'Total Borrowing' },
],
},
],
In this configuration:
totalType
specifies whether the value is a Total or Subtotal.index
determines the position in the data after which the Total or Subtotal will appear.axisLabel
is used to provide a unique label, used as a category on the Category Axis.
Customisation
Series Items
Series items are customised via the item
configuration object.
series: [
{
type: 'waterfall',
xKey: 'financials',
yKey: 'amount',
item: {
positive: {
fill: '#4A90E2',
stroke: '#4A90E2',
},
negative: {
fill: '#FF6B6B',
stroke: '#FF6B6B',
},
total: {
name: 'Total / Subtotal',
fill: '#404066',
stroke: '#404066',
},
},
},
],
In this configuration:
positive
andnegative
change Positive/Negative series items.total
changes Total/Subtotal series items.
Note that the total
series item also contains a name
property to change the total name to 'Total / Subtotal' in the Total legend item and tooltips.
Connector Lines
Connector lines between the bars can be customised using the line
property.
series: [
{
type: 'waterfall',
xKey: 'financials',
yKey: 'amount',
line: {
strokeWidth: 4,
stroke: 'red',
},
},
],
To remove the connector lines, set line.enabled
to false
.
Horizontal Waterfall
To show a Horizontal Waterfall Series, set direction: 'horizontal'
.
series: [
{
type: 'waterfall',
direction: 'horizontal',
xKey: 'financials',
yKey: 'amount',
},
],
When the direction
is 'horizontal'
the xKey
will define categories on the y-axis, while the yKey
will represent numerical values along the x-axis.
API Reference
Properties available on the AgWaterfallSeriesOptions
interface.
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 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-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.