Waterfall

A waterfall shows how a running total gets from where it starts to where it ends. Each change is a bar floating from the total before it to the total after, coloured by whether it adds or takes away, totals stand on zero, and a connector carries the total across from each bar to the next.

The waterfall ships as its own package, @graphysdk/geom-waterfall, on a 0.x version line. While it is on 0.x, a minor release may change its aesthetics, style parts or look; pin a caret range (^0.1.0) to take only patches. Tell us what works and what doesn’t on Discord.

Install

npm install @graphysdk/geom-waterfall

It peer-depends on @graphysdk/react and nothing else. Register the plugin once with createGraphyKit, which adds kit.geom.waterfall() and binds kit.GraphProvider to the same plugin:

import {
  createGraphyKit,
  GraphRenderer,
  highlight,
  styles,
} from '@graphysdk/react';
import { waterfall } from '@graphysdk/geom-waterfall';

const kit = createGraphyKit({ plugins: [waterfall] });

One bar per change

Pass one row per bar, in the order the total runs. Map the category to x and the change to y, and map measure to a column saying which rows are totals:

const data = {
  columns: [{ key: 'item' }, { key: 'amount' }, { key: 'measure' }],
  rows: [
    { item: 'Revenue', amount: 1250, measure: 'absolute' },
    { item: 'Cost of sales', amount: -480 },
    { item: 'Gross profit', measure: 'total' },
    { item: 'Sales & marketing', amount: -210 },
    // …
    { item: 'Net income', measure: 'total' },
  ],
};

const spec = kit.pipe(
  kit.createSpec({ x: 'item', y: 'amount' }),
  kit.geom.waterfall({ aes: { measure: 'measure' } }),
  kit.scale.x.discrete(),
  kit.scale.y.continuous()
);

export function ProfitBridge() {
  return (
    <kit.GraphProvider spec={spec} data={data}>
      <GraphRenderer />
    </kit.GraphProvider>
  );
}

The value axis fits the running totals rather than the changes, and holds zero, since a bar is a length. The category axis is always discrete. The total runs in data order, and each connector joins a bar to the next row’s bar. Sort the rows, not the axis: a discrete domain that reorders the categories moves the bars but not the total, so the connectors then skip across bars.

Totals

measure reads each row as one of three kinds, the names Plotly uses:

Measure	The bar
`'relative'`	Moves the running total by `y`. An empty cell reads so.
`'total'`	Draws the running total so far, from zero. Its own `y` may be empty.
`'absolute'`	Draws `y` from zero, and sets the running total to it.

Without measure, every row is a step. Any other value is an error. Use 'absolute' for an opening balance, and 'total' for each subtotal and the closing figure:

Running totals already in the data

When the data already holds each bar’s running total before and after, as a finance tool exports a bridge, set the layer’s stat to identity and map start and end instead of y. measure still marks the totals, which colour apart from the steps:

kit.geom.waterfall({
  stat: kit.stat.identity(),
  aes: { start: 'opening', end: 'closing', measure: 'measure' },
});

Under identity, a missing start or end is an error. Under the default stat, mapping either is an error too, since the stat computes them from y.

Horizontal

Add kit.coord.flip(). The categories move to the vertical axis and the bars run across.

Bar width and connectors

width sets how much of its band each bar spans, as a fraction from just above 0 up to 1. It defaults to 0.8, which leaves a gap for the connector; at 1 neighbouring bars touch. A width above 1 is clamped to the full band, and one at or below 0 falls back to the default; the compiler warns in both cases. connector sets how the running total is carried from each bar to the next: 'spanning' (the default) runs the line across both bars, along their edges, and 'between' runs it across the gap only. To hide connectors, style them: kit.style.geom.waterfall.connector({ alpha: 0 }) hides every one, and a where hides only those leaving the bars it picks. An unknown value falls back to 'spanning' with a warning.

kit.geom.waterfall({
  aes: { measure: 'measure' },
  params: { width: 0.6, connector: 'between' },
});

Styling

The bars are the observations, and each kind and the connectors have a builder of their own. A bar’s colour says what the step did, so a chart-wide style.geom() does not recolour it:

Builder	Properties	Default
`kit.style.geom.waterfall()`	`alpha`, `fillAlpha`, `strokeWidth`	Opaque, no border
`kit.style.geom.waterfall.increase()`	`fill`, `stroke`	The positive trend colour
`kit.style.geom.waterfall.decrease()`	`fill`, `stroke`	The negative trend colour
`kit.style.geom.waterfall.total()`	`fill`, `stroke`	The neutral trend colour
`kit.style.geom.waterfall.connector()`	`stroke`, `alpha`, `strokeWidth`, `dashArray`	A 1px line

const spec = kit.pipe(
  // …
  styles({
    defaults: [
      kit.style.geom.waterfall({ fillAlpha: 0.85 }),
      kit.style.geom.waterfall.increase({ fill: '#7fb685' }),
      kit.style.geom.waterfall.decrease({ fill: '#d98a7e' }),
      kit.style.geom.waterfall.total({ fill: '#3a3833' }),
      kit.style.geom.waterfall.connector({
        stroke: '#898373',
        dashArray: [3, 3],
      }),
    ],
  })
);

A connector is styled against the bar it leaves, so an entry’s where can pick connectors out by that bar’s values.

Colour through a scale

To colour the kinds through the colour scale, with a legend, map color to waterfallKind. A mapped colour beats the kind builders’ defaults entries; an overrides entry still beats it. The connectors keep their own colour.

const spec = kit.pipe(
  kit.createSpec({ x: 'item', y: 'amount' }),
  kit.geom.waterfall({ aes: { measure: 'measure', color: 'waterfallKind' } }),
  kit.scale.x.discrete(),
  kit.scale.y.continuous(),
  kit.scale.color.discrete({
    domain: ['increase', 'decrease', 'total'],
    range: ['#2a9d8f', '#e76f51', '#264653'],
  })
);

The running-total variables

The geom writes four variables you can name in a highlight or an entry’s where:

Variable	Value
`waterfallStart`	The running total the bar starts from, in `y`’s units
`waterfallEnd`	The running total the bar ends on, in `y`’s units
`waterfallKind`	`'increase'`, `'decrease'` or `'total'`
`waterfallValue`	The figure the bar shows: its change, or the total it draws

Under stat: 'identity' your own start and end columns hold the running totals, so the geom writes only waterfallKind and waterfallValue. y keeps the values you passed. A pinned number or a difference arrow reads waterfallValue. An absolute bar is a 'total' kind; highlight on your measure column to pick it out.

Hover and highlight

Hovering anywhere in a category’s band emphasises its bar, and the tooltip lists its value and the running total it lands on. A highlight raises each matched bar. The connectors stay with the dimmed layer:

const spec = kit.pipe(
  // …
  highlight({ variable: 'waterfallKind', eq: 'total' })
);

Not yet supported

The editor’s chart-type picker and the chart agent. In editable mode the waterfall renders, hovers, selects and takes annotations on each bar’s running total, but it is authored in code.
Dodged groups. Each group runs its own total, but groups on the same category overlap rather than sitting side by side.
Data labels. dataLabels prints nothing on a bar yet.

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Install

One bar per change

Totals

Running totals already in the data

Horizontal

Bar width and connectors

Styling

Colour through a scale

The running-total variables

Hover and highlight

Not yet supported

​Install

​One bar per change

​Totals

​Running totals already in the data

​Horizontal

​Bar width and connectors

​Styling

​Colour through a scale

​The running-total variables

​Hover and highlight

​Not yet supported

Install

One bar per change

Totals

Running totals already in the data

Horizontal

Bar width and connectors

Styling

Colour through a scale

The running-total variables

Hover and highlight

Not yet supported