Opening to closing value, one step at a time. Sample data: Q3 2026 cash bridge, $1.82M opening to $1.91M closing.
Installation
- 1
Set up the registry once
This chart is free in Hearth and MIT licensed: no token. Add @chartory to components.json once (the URL alone, no headers), or skip this when another chart is already installed.
Installation guide - 2
Add the chart
One command adds the Waterfall component to your project.
npx shadcn add @chartory/waterfall - 3
Use it
Pass your data. size and legend are the Figma properties.
usage.tsximport { Waterfall } from "@/components/chartory/waterfall"<Waterfall data={cashBridge} size="m" legend/>
Props
<Waterfall>
Every prop but data is a Figma property with the same name and values.
WaterfallData
The data prop: one object for the whole chart.
WaterfallStep
One object per entry in steps.
The data as a JSON Schema: schemas/waterfall.json
Waterfall chart: a React and Figma chart in four sizes
- Data shape
- Opening total, signed steps, closing total
- Good for
- Cash bridges, profit walks, budget against actual
- Avoid when
- Steps have no order, or the parts make up one whole
- Sizes
- XS, S, M and L, re-laid out from the data
At a glance
What does a waterfall chart show?
A waterfall chart shows how an opening value turns into a closing value through a run of gains and losses. Each bar starts where the last one ended, so you see which step moved the total and by how much.
Chartory ships it as a Figma component and a React component with the same name. The code installs from the shadcn registry with one command and lands in your project as a file you own.
What is the Waterfall chart?
It is one <Waterfall> component driven by data, size, legend and color. The data is an opening total, signed steps and a closing total: steps with a label, a value v and, for the totals, total, plus the scale (max, ticks) and a fmt for the labels.
Sizes XS, S, M and L re-lay the chart out from the data instead of scaling it, so labels stay readable at every size.
When should I use it?
- One total turns into another: Opening cash to closing cash, revenue to profit.
- The steps run in a set order: Sales, then refunds, staff, cloud and tax.
- Gains and losses share one axis: Rises and drops start from the same running total.
When does another type fit better?
- The parts make up one whole: No order and no running total: use a Treemap.
- You follow one value over time: A trend, not a bridge between two totals: use a Line chart.
- Flows split into several paths: A step feeds more than one next step: use a Sankey.
Waterfall questions
Installing, data, Figma and plans.
Yes. It installs through the shadcn registry with the shadcn CLI, and the file lands in your project.
It is free in Hearth and MIT licensed: add the @chartory registry URL once, no token, then run npx shadcn add @chartory/waterfall. The Installation guide has the steps.
Yes. Connect the Chartory MCP server and ask for the waterfall chart; the agent runs the same command and you review the diff.
One WaterfallData object: steps in order (a label and a value v each, with total set on the opening and closing totals), the scale top max, the axis ticks and a fmt function for the labels.
XS, S, M and L, in Figma and in code. Each size is laid out again from the data, so text and lines keep their size.
Yes. chart/042-waterfall-cash-bridge has the same size, legend and color properties as the component.
Yes. Every paint is a token, so the chart follows the mode and the preset, Chartory or Ember, light or dark.
None for Hearth: it is free in the public registry, no token. The Signal collection (@chartory/signal) comes with Code and Complete.