Waterfall Chart
Bridge chart carrying a running total through signed steps. Install with npx remotion-ui@latest add waterfall-chart.
PrimitiveData & mediaAdvanced
$ npx remotion-ui@latest add waterfall-chartFloating bars that carry a running total from one figure to another.
import { WaterfallChart } from "@/remotion/primitives/waterfall-chart";
<WaterfallChart
steps={[
{ label: "Q1 open", value: 320, isTotal: true },
{ label: "New", value: 180 },
{ label: "Churn", value: -74 },
{ label: "Q2 close", value: 484, isTotal: true },
]}
staggerInFrames={15}
/>Bars grow from the running total
Each bar starts at the level the previous step left behind and grows by its own change. That is what separates a waterfall from a bar chart: position carries as much information as length, and growing every bar from the axis would throw the position away.
Subtotals
A step marked isTotal is drawn from the axis and resets the running total to
its own value — that is how an opening or closing column stays honest instead of
being a bar that happens to reach the same height.
Signs come from the values themselves: a rise takes upColor, a fall
downColor, a total totalColor, and the printed change keeps its sign.
Connectors
Dashed connectors leave the level a step lands on and wait for that bar to stop moving, so they never point at a level still in flight. They are skipped in front of a subtotal, which starts from the axis rather than from the step before it.
Bars grow from the running total they start at, not from the axis: in a waterfall the position carries as much as the length. `isTotal` draws from the axis and resets the running total, which is how an opening or closing column stays honest. Connectors wait for their bar to stop before extending.
Agent notes
Install first, then import the copied source component locally. AI guide →
@/remotion/primitives/waterfall-chart- Use when: data stories, metrics, charts, and numeric proof points.
- Customize: steps, width, height, upColor, plus copied source for timing, layout, colors, and typography.
- Rule: do not import this component from the
remotion-uinpm package; it is copied into your project.
Usage
import { WaterfallChart } from "@/remotion/primitives/waterfall-chart";
<WaterfallChart
steps={[
{ label: "Q1 open", value: 320, isTotal: true },
{ label: "New", value: 180 },
{ label: "Churn", value: -74 },
{ label: "Q2 close", value: 484, isTotal: true },
]}
staggerInFrames={15}
/>API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| steps | WaterfallStep[] | required | `{ label, value, isTotal?, color? }`. `value` is a signed change unless `isTotal`. |
| width | number | 860 | Drawing width. Type scales off it. |
| height | number | 440 | Drawing height. |
| upColor | string | "#2dd4bf" | Bars that add to the running total. |
| downColor | string | "#f472b6" | Bars that subtract. |
| totalColor | string | "#e8b86d" | Subtotal columns drawn from the axis. |
| showConnectors | boolean | true | Dashed rules from one bar's landing level to the next bar's base. |
| showValues | boolean | true | Signed change printed above or below each bar. |
| showAxis | boolean | true | Gridlines and value labels down the left gutter. |
| durationInFrames | number | 20 | Length of one bar's growth. |
| staggerInFrames | number | 10 | Frames between one step and the next. |
| exitAtInFrames | number | undefined | Frame the bridge starts clearing on, left to right. |
| frame | number | undefined | Frame override — pass the parent frame inside a `<Sequence>`. |