JavaScript ChartsWaterfall Series

Version 14.2.0

Enterprise

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 Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  WaterfallSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  WaterfallSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "UK Government Budget",
  },
  subtitle: {
    text: "All values in £ billions",
  },
  series: [
    {
      type: "waterfall",
      xKey: "financials",
      xName: "Financials",
      yKey: "amount",
      yName: "Amount",
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      financials: "Income\nTax",
      amount: 185,
    },
    {
      financials: "VAT",
      amount: 145,
    },
    {
      financials: "NI",
      amount: 134,
    },
    {
      financials: "Corp\nTax",
      amount: 55,
    },
    {
      financials: "Council\nTax",
      amount: 34,
    },
    {
      financials: "Social\nProtection",
      amount: -252,
    },
    {
      financials: "Health",
      amount: -155,
    },
    {
      financials: "Education",
      amount: -112,
    },
    {
      financials: "Defence",
      amount: -65,
    },
    {
      financials: "Debt\nInterest",
      amount: -63,
    },
    {
      financials: "Housing",
      amount: -31,
    },
  ];
}

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 Copy Link

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.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  WaterfallSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  WaterfallSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "UK Government Budget",
  },
  subtitle: {
    text: "All values in £ billions",
  },
  series: [
    {
      type: "waterfall",
      xKey: "financials",
      xName: "Financials",
      yKey: "amount",
      yName: "Amount",
      totals: [
        {
          totalType: "subtotal",
          index: 4,
          axisLabel: "Total Revenue",
          itemId: "total-revenue",
        },
        {
          totalType: "subtotal",
          index: 9,
          axisLabel: "Total Expenditure",
          itemId: "total-expenditure",
        },
        {
          totalType: "total",
          index: 9,
          axisLabel: "Total Borrowing",
          itemId: "total-borrowing",
        },
      ],
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      financials: "Income Tax",
      amount: 185,
    },
    {
      financials: "VAT",
      amount: 145,
    },
    {
      financials: "NI",
      amount: 134,
    },
    {
      financials: "Corp Tax",
      amount: 55,
    },
    {
      financials: "Council Tax",
      amount: 34,
    },
    {
      financials: "Health",
      amount: -155,
    },
    {
      financials: "Education",
      amount: -112,
    },
    {
      financials: "Defence",
      amount: -165,
    },
    {
      financials: "Interest",
      amount: -163,
    },
    {
      financials: "Housing",
      amount: -91,
    },
  ];
}

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', itemId: 'total-revenue' },
                { totalType: 'subtotal', index: 9, axisLabel: 'Total Expenditure', itemId: 'total-expenditure' },
                { totalType: 'total', index: 9, axisLabel: 'Total Borrowing', itemId: '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 the label shown as a category on the Category Axis.
itemId is an optional unique identifier for the total, surfaced in events and callbacks. Totals that share an axisLabel must each set a unique itemId to remain distinguishable.

Customisation Copy Link

Series Items Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  WaterfallSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  WaterfallSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "UK Government Budget",
  },
  subtitle: {
    text: "All values in £ billions",
  },
  series: [
    {
      type: "waterfall",
      xKey: "financials",
      xName: "Financials",
      yKey: "amount",
      yName: "Amount",
      item: {
        positive: {
          fill: "#4A90E2",
          stroke: "#4A90E2",
        },
        negative: {
          fill: "#FF6B6B",
          stroke: "#FF6B6B",
        },
        total: {
          name: "Total / Subtotal",
          fill: "#404066",
          stroke: "#404066",
        },
      },
      totals: [
        { totalType: "subtotal", index: 4, axisLabel: "Total Revenue" },
        {
          totalType: "subtotal",
          index: 9,
          axisLabel: "Total Expenditure",
        },
        { totalType: "total", index: 9, axisLabel: "Total Borrowing" },
      ],
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      financials: "Income Tax",
      amount: 185,
    },
    {
      financials: "VAT",
      amount: 145,
    },
    {
      financials: "NI",
      amount: 134,
    },
    {
      financials: "Corp Tax",
      amount: 55,
    },
    {
      financials: "Council Tax",
      amount: 34,
    },
    {
      financials: "Health",
      amount: -155,
    },
    {
      financials: "Education",
      amount: -112,
    },
    {
      financials: "Defence",
      amount: -165,
    },
    {
      financials: "Interest",
      amount: -163,
    },
    {
      financials: "Housing",
      amount: -91,
    },
  ];
}

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 and negative 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 Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  WaterfallSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  WaterfallSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "UK Government Budget",
  },
  subtitle: {
    text: "All values in £ billions",
  },
  series: [
    {
      type: "waterfall",
      xKey: "financials",
      xName: "Financials",
      yKey: "amount",
      yName: "Amount",
      line: {
        strokeWidth: 4,
        stroke: "red",
      },
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      financials: "Income \nTax",
      amount: 185,
    },
    {
      financials: "VAT",
      amount: 145,
    },
    {
      financials: "NI",
      amount: 134,
    },
    {
      financials: "Corp \nTax",
      amount: 55,
    },
    {
      financials: "Council \nTax",
      amount: 34,
    },
    {
      financials: "Social \nProtection",
      amount: -252,
    },
    {
      financials: "Health",
      amount: -155,
    },
    {
      financials: "Education",
      amount: -112,
    },
    {
      financials: "Defence",
      amount: -65,
    },
    {
      financials: "Debt \nInterest",
      amount: -63,
    },
    {
      financials: "Housing",
      amount: -31,
    },
  ];
}

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 Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  WaterfallSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  WaterfallSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "UK Government Budget",
  },
  subtitle: {
    text: "All values in £ billions",
  },
  series: [
    {
      type: "waterfall",
      direction: "horizontal",
      xKey: "financials",
      xName: "Financials",
      yKey: "amount",
      yName: "Amount",
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      financials: "Income Tax",
      amount: 185,
    },
    {
      financials: "VAT",
      amount: 145,
    },
    {
      financials: "NI",
      amount: 134,
    },
    {
      financials: "Corp Tax",
      amount: 55,
    },
    {
      financials: "Council Tax",
      amount: 34,
    },
    {
      financials: "Social Protection",
      amount: -252,
    },
    {
      financials: "Health",
      amount: -155,
    },
    {
      financials: "Education",
      amount: -112,
    },
    {
      financials: "Defence",
      amount: -65,
    },
    {
      financials: "Debt Interest",
      amount: -63,
    },
    {
      financials: "Housing",
      amount: -31,
    },
  ];
}

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 values will be plotted on the default y axis, while the yKey values will be plotted on the default x axis. values along the x-axis.

Waterfall Chart Examples Copy Link

See more Waterfall Chart examples in the AG Charts Gallery.

Waterfall Chart Example

Horizontal Waterfall Chart Example

Customised Waterfall Chart Example

API Reference Copy Link

Properties available on the AgWaterfallSeriesOptions interface.

type required 'waterfall': Configuration for the Waterfall Series.
xKey required DatumKey: The key to use to retrieve x-values from the data.
yKey required DatumKey: The key to use to retrieve y-values from the data.
totals WaterfallSeriesTotalMeta[]: Configuration of total and subtotal values.
id string default: 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.
context ContextDefault: Context object to use in callbacks.
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.
cursor string: The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
highlight AgHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
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.
xKeyAxis string default: 'x': The key of the x-axis to which this series is bound.
yKeyAxis string default: 'y': The key of the y-axis to which this series is bound.
xName string: 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.
yName string: 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.
direction 'horizontal' | 'vertical': Bar rendering direction. __Note:__ This option affects the layout direction of X and Y data values.
item AgWaterfallSeriesItem: Configuration used for the waterfall series item types.
line AgWaterfallSeriesLineOptions: Configuration for the connector lines.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
width PixelSize: Fixed width of each bar in the series.
widthRatio Ratio: Ratio of the bandwidth (or specified width) to use for the width for each bar in the series.
showInMiniChart boolean: Whether to include the series in the Mini Chart.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsWaterfall Series

Simple Waterfall Copy Link

Total / Subtotal Values Copy Link

Customisation Copy Link

Series Items Copy Link

Connector Lines Copy Link

Horizontal Waterfall Copy Link

Waterfall Chart Examples Copy Link

API Reference Copy Link