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": "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.
{
"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.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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": 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": 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.