# Waterfall

> Opening to closing value, one step at a time. Sample data: Q3 2026 cash bridge, $1.82M opening to $1.91M closing.

- Type 042 · Flow between steps
- Component: `<Waterfall>`, the same name as the Figma component
- Install: `npx shadcn add @chartory/waterfall` (free in Hearth: the public registry, no token; Signal with Code and Complete)
- Type page: https://usechartory.com/charts/waterfall

## 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](https://usechartory.com/docs/installation)

2. **Add the chart.** One command adds the Waterfall component to your project.

```bash
npx shadcn add @chartory/waterfall
```

3. **Use it.** Pass your data. size and legend are the Figma properties.

usage.tsx:

```tsx
import { 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.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| data | WaterfallData | Required | The chart's data. The tables below list every field. |
| size | "xs" \| "s" \| "m" \| "l" | "m" | The size class. Each one is laid out again from the data. |
| legend | boolean | true | Shows the legend row under the plot. |
| color | "cat-1" \| "cat-2" \| "cat-3" \| "cat-4" | "cat-1" | The data colour of the primary marks (data/primary). |

### WaterfallData

The data prop: one object for the whole chart.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| max | number | Required | The top of the value scale. |
| ticks | string[] | Required | The axis tick labels. |
| fmt | (v: number) => string | Required | Formats a value for its label. |
| steps | WaterfallStep[] | Required | One entry per step. |
| stagger? | "auto" \| boolean | — | Step names wider than their column: every other one on a second row (the plot's base rises one row). "auto"
(site cards with long names): one row, or two when two names would touch, so no x label is ever dropped. |

### WaterfallStep

One object per entry in steps.

| Prop | Type | Default | Note |
| --- | --- | --- | --- |
| label | string | Required | The name shown on the chart. |
| v | number | Required | The value. |
| total? | boolean | false | Draws the bar up from zero, as a total. |

## 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 |

### 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

### Does the Waterfall chart work with shadcn/ui?

Yes. It installs through the shadcn registry with the shadcn CLI, and the file lands in your project.

### How do I install it?

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.

### Can my coding agent install it?

Yes. Connect the Chartory MCP server and ask for the waterfall chart; the agent runs the same command and you review the diff.

### What data does it expect?

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.

### Which sizes does it ship in?

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.

### Is it in the Figma file too?

Yes. chart/042-waterfall-cash-bridge has the same size, legend and color properties as the component.

### Does it follow light and dark mode?

Yes. Every paint is a token, so the chart follows the mode and the preset, Chartory or Ember, light or dark.

### Which plan has the code?

None for Hearth: it is free in the public registry, no token. The Signal collection (@chartory/signal) comes with Code and Complete.