@graphysdk/geom-waterfall
Beta. This geom is on a
0.xversion line: a minor release may change its aesthetics, style parts or look. Use a caret range (^0.1.0) to take only patches.
A waterfall geom for the Graphy charting SDK. It shows how a running total gets from where it starts to where it ends: one floating bar per change, coloured by whether it adds or takes away, with totals standing on zero and a connector carrying the total from each bar to the next.
Learn more at graphy.dev.
Install
npm install @graphysdk/geom-waterfall @graphysdk/react
Requires React 19. Its only peer is @graphysdk/react.
Usage
Data is one row per bar, in the order the total runs. Map the category to x and the change to y. Map measure to a column that marks a row 'total' (draw the running total so far) or 'absolute' (set the running total to the row's value); an empty or 'relative' row is a step, and any other value is an error:
import { createGraphyKit, GraphRenderer } from '@graphysdk/react';
import { waterfall } from '@graphysdk/geom-waterfall';
const kit = createGraphyKit({ plugins: [waterfall] });
const data = {
columns: [{ key: 'item' }, { key: 'amount' }, { key: 'measure' }],
rows: [
{ item: 'Opening', amount: 100, measure: 'absolute' },
{ item: 'Sales', amount: 60 },
{ item: 'Payroll', amount: -50 },
{ item: 'Closing', 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 CashFlow() {
return (
<kit.GraphProvider spec={spec} data={data}>
<GraphRenderer />
</kit.GraphProvider>
);
}
When the running totals are already in the data, set stat: kit.stat.identity() and map start and end instead of y; measure still marks the totals. To colour the kinds through a scale with a legend, map color: 'waterfallKind'.
params.width sets each bar's share of its band, in (0, 1] (default 0.8), and params.connector sets where the line carrying the total between bars runs: 'spanning' (default) or 'between'.
Colour the bars with kit.style.geom.waterfall.increase(), .decrease() and .total(), the lines between them with kit.style.geom.waterfall.connector() (alpha: 0 hides them, and a where picks the ones leaving some bars), and the bars' shared look with kit.style.geom.waterfall().
Docs
Feedback
This geom is released early to hear what works. Tell us on Discord.
Licence
This package is available under PolyForm Noncommercial, Small Business, or a 32-day Free Trial. Free Trial is local or internal evaluation only — it does not cover a public page. See what you can do under the trial.
For a commercial licence, talk to us.