Waterfall Chart React component
A waterfall (bridge) chart that explains how a number got from A to B: floating bars for each increase and decrease, totals anchored to zero, dashed connectors, signed value labels, a net change in the header and a running-total tooltip.
About the Waterfall Chart component
Waterfall Chart, also called a bridge chart, explains how a number moved from one value to another: an opening bar, a floating bar for every increase and decrease, and a closing total, joined by dashed connectors so you can follow the running total.
Each bar carries its signed change, the header shows the end value and net change, and hovering or using the arrow keys shows a bar's change, its share of the start and the running total.
When to use it
Use it for ARR and MRR bridges (new, expansion, churn), profit and loss walks, budget vs actual, headcount changes, cash flow and inventory movements.
Give each step a short label; with more than about 12 steps the bars get thin, so group small items together.
Installation
Add the Waterfall Chart component to your project with the shadcn CLI. It lands in components/waterfall-chart.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/waterfall-chartOr copy the source by hand and install its dependencies:
npm install clsx tailwind-mergeProps
<WaterfallChart /> accepts 9 props, all optional. It also accepts the usual <div> attributes, like className, style, id and aria-*, and passes them to its root element.
| Prop | Type | Default |
|---|---|---|
| theme | "dark" | "light" | "dark" |
| title | string | "ARR bridge" |
| subtitle | string | "What moved annual recurring revenue from Q1 to Q2" |
| steps | { label: string; value?: number; kind?: "start" | "delta" | "total" }[] | DEFAULT_STEPS |
| upColor | string | — |
| downColor | string | — |
| totalColor | string | — |
| height Height of the plot area, in px. | number | 300 |
| formatValue | (value: number) => string | (v) => money.format(v) |
- theme"dark" | "light"Default: "dark"
- titlestringDefault: "ARR bridge"
- subtitlestringDefault: "What moved annual recurring revenue from Q1 to Q2"
- steps{ label: string; value?: number; kind?: "start" | "delta" | "total" }[]Default: DEFAULT_STEPS
- upColorstring
- downColorstring
- totalColorstring
- height
Height of the plot area, in px.
numberDefault: 300 - formatValue(value: number) => stringDefault: (v) => money.format(v)
npm dependencies
Installed for you by the shadcn CLI.
Waterfall Chart FAQ
- How do I describe the steps?
- Each step is { label, value?, kind? }. The first is a start (its value is the opening amount); the rest are deltas (positive adds, negative subtracts). Add { kind: "total" } anywhere to show the running total as a full bar, for subtotals or the closing value.
- Can I change the colours?
- upColor, downColor and totalColor override green, red and blue. formatValue formats every number (default: compact dollars like $1.2M).
- Why do totals start at zero?
- Totals are absolute amounts, so they're drawn from zero to stay honest; only the deltas float.
- Is it accessible?
- The chart is focusable with a summary of every step; arrow keys, Home and End move between bars and Escape clears the tooltip. With reduced motion the bars appear in place.
