A waterfall chart is a data visualization that helps illustrate how an initial value changes through a series of additions and subtractions to reach a final value. Each column represents a step in the process, with increases shown in one color and decreases in another. The chart is commonly used in financial analysis, budgeting, and performance tracking to break down changes in revenue, profit, or costs over time.

• Usage: 🧵 Pattern 🌡️ Range
• Types:
  • Waterfall bar chart renders a waterfall chart using horizontal bars.
  • Waterfall column chart renders a waterfall chart using vertical columns.

Unlike traditional bar charts, waterfall charts highlight incremental changes rather than absolute values, making it easier to analyze contributions to a total. They are particularly useful for understanding profit and loss statements, cash flow analysis, and operational performance by visually showing where gains and losses occur within a process.

💡 See the js-chart-examples repo for many detailed examples of how to use and customize (style) different types of waterfall charts.

Waterfall Bar Charts and Waterfall Column Charts require the following files to render correctly.

Waterfall charts accept the following chart attributes.

🧱 class | 🗂️ type | 🕒 version | 📋 template | ↔️ width | ↕️ height | 📄 title | 📄 ytitle | 📄 xtitle | 📏 scalemin | 📏 scalemax | 🔲 showborder | 🏷️ showlabels | 📘 showlegend | 🎮 showcontrols | 🗂️ showdatatable | #️⃣ showgridlines | ➖ showzeroline | 📲 showwidget

The js-labels input container sets the labels that anchors each cluster on the axis (e.g., different months, regions, or items).

The container accepts a comma-separated list of text values.

<div class="js-labels">label-0, label-1, label-2, ..., label-n</div>

The example below sets the category labels on a chart to the months of the year.

<div class="js-labels">Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec</div>

The js-values input container sets the individual data series (or data sets) on a chart.

The container accept a comma-separated list of numeric values.

<div class="js-values">10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120</div>

The js-values input container accepts a title attribute that is used to set a name or short description for the data series (or data set).

<div class="js-values" title="Sales revenue 2024">10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120</div>

ℹ️ A title will automatically be assigned to each data series (or data set) if no title attribute is assigned to the js-values container.

Clustered data series (or multiple data series) can be set by specifying multiple js-values input containers. Each container represents a single data series (or data set).

<div class="js-values" title="Sales revenue 2024">20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130</div>
<div class="js-values" title="Sales revenue 2023">15, 25, 35, 45, 55, 65 75, 85, 95, 105, 115, 125</div>
<div class="js-values" title="Sales revenue 2022">10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120</div>

Every chart is customized (or styled) using one of the supported style templates.

Style directives are used to override the customization applied by the style template to each chart.

Waterfall charts support the following style directives.

🖼️ js-canvas-* | 📊 js-chart-* | 🎨 js-color-* | 🖱️ js-control-button-* | 🏷️ js-datalabel-* | 🗂️ js-datatable-* | 🦶 js-footer-* | #️⃣ js-grid-line-* | 📘 js-legend-* | 🎮 js-options-menu-* | 📏 js-scale-* | 📄 js-title-* | 🧱 js-value-bar-* | ➖ js-zero-line-*

💡 See the 👀 js-chart-examples repo for many detailed examples of how to use the style directives to customize a chart.

💡 See the js-chart-examples repo for many detailed examples of how to use different types of waterfall charts.

The example below renders a waterfall chart, showing Income and expenses - Q3 of a fictional company.

<div class="js-chart" type="waterfall bar" width="700px" title="Income and expenses - Q3" xtitle="Movement" ytitle="Euro" showlegend="off" showgridlines="yes" showzeroline="yes" showdatatable="no">
    <div class="js-labels">Opening balance, Rent, Repairs, Insurance, Payment invoice #455, Stationary</div>
    <div class="js-values" title="Q3 Income and Expenses">15766, -9321, -5214, -4520, 2345, -1756</div>

    <div class="js-value-bar-min-width">2px</div>
    <div class="js-value-bar-series-margin">5px</div>
</div>

The js-labels input container sets the labels that anchor each cluster on the axis. In this example, each cluster represents one quarter in the year.

There are three js-values input containers. Each container represents one data series (or data set) on the chart. In the example, each container represents one product line.

• The js-value-bar-min-width style directive ensures that all cells on the chart are not rendered below 2px in height.
• The js-value-bar-series-margin style directive creates a 5px gap between the bars on the chart.