Waterfall

A waterfall shows how a total changes. Each step is a gain or a loss, floating on the running total. A total row is a bar from zero. A connector joins one step to the next.

When to use it

Use a waterfall when the question is what added and what subtracted between two totals. Year to date opens at 120, adds won and expand, subtracts lost, and closes at 160. ARR bridge is the same reading for a recurring total. One voyage, step by step opens a voyage, adds crane and berth, subtracts cloth, and closes.

A bar compares independent amounts. The bars do not float, and a later bar is not a change from the previous one. A funnel is a size at each stage. It does not draw a gain, and it has no total row.

Waterfall, bar, and funnel

All three can show a number for each name. The encoding is what changes.

type: "waterfall" adds each amount to a running total. A positive step rises. A negative step falls. A total row replaces the running total.

type: "bar" draws each amount from the baseline. mark.orientation can turn those bars horizontal. That key does not apply to a waterfall.

type: "funnel" keeps data order and sets the width from the value. There is no signed step and no connector.

Data

Each row is one step. Point encoding.x at the name and encoding.y at the amount. A positive amount is a gain. A negative amount is a loss. The running total starts at zero and adds each delta. Year to date uses step and amount. ARR bridge uses step and delta.

A total row is not a delta. Put true in the total field and the bar runs from zero to that amount. The running total then becomes that amount. The field name defaults to total. Year to date and ARR bridge set mark.total to total. If the flag lives in another column, set mark.total to that column's name.

mark.total
{
  "mark": { "total": "total" }
}

A missing number is skipped. a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest waterfall. version, type, and a11y.alt are required. Open, one gain, close. The total flag uses the default field name, and the amounts are labeled, so mark can be omitted.

spec.json
{
  "version": "1",
  "type": "waterfall",
  "data": [
    {
      "step": "Open",
      "amount": 120,
      "total": true
    },
    {
      "step": "Won",
      "amount": 40
    },
    {
      "step": "Close",
      "amount": 160,
      "total": true
    }
  ],
  "encoding": {
    "x": "step",
    "y": "amount"
  },
  "a11y": {
    "alt": "The close is 160 after one gain."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/waterfallBundle@chartkitdev/core/extraFamilyStatistical
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing waterfall specs. Year to date is the core example. ARR bridge is the homepage chart, in millions. One voyage, step by step formats the amount as pounds and names the tooltip.

Labels

The step name is on the axis. mark.labels draws the number above the bar. Omit the key, or set true, and a delta shows the change. A total shows the level it lands on. false hides the number. The axis name stays.

mark.labels
{
  "mark": { "labels": false }
}

mark.labelFormat formats that number. Change it in the playground. Turning labels off and on again puts the example's format back. An example that omitted mark.labels gets the key removed, so the default stays on.

Tooltip

tooltip is on for a waterfall when the key is omitted. Hovering a bar shows the step and its amount. A total is labeled as a total. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card, and tooltip.position places it. One voyage, step by step sets a top card with the amount in pounds. Change those in the playground. Turning the card off and on again puts that object back.

The rest of the spec

Connectors are always drawn, as a dashed line from the end of one step to the start of the next. mark.gap is the space between bars, as a fraction of the band. The colors come from the theme: positive for a gain, negative for a loss, and accent for a total. There is no legend. Those colors are not a series. Theme presets live on the playground, with the full option list.