# Waterfall Chart (/docs/charts/components/waterfall)

Use a waterfall chart to show how a running balance, like cash or headcount, moves from one checkpoint to the next through each change.

<Example caption="Hover a bar, or focus the chart and press the arrow keys, to see that step's change or balance.">
<Basic />

```tsx
"use client";

import {
  Cell,
  computeWaterfallData,
  type SeriesConfig,
  WaterfallChart,
  type WaterfallEntry,
} from "@kind-ui/charts";

const entries = [
  { id: "opening", label: "Opening", kind: "start", value: 120 },
  { id: "sales", label: "Sales", kind: "delta", value: 75 },
  { id: "refunds", label: "Refunds", kind: "delta", value: -15 },
  { id: "subtotal", label: "Subtotal", kind: "subtotal" },
  { id: "costs", label: "Costs", kind: "delta", value: -65 },
  { id: "tax", label: "Tax", kind: "delta", value: -20 },
  { id: "closing", label: "Closing", kind: "end", value: 95 },
] satisfies WaterfallEntry[];

const data = computeWaterfallData(entries);

const config = {
  range: { label: "Cash", color: "#733bff" },
} satisfies SeriesConfig;

const labels = new Map(data.map((row) => [row.id, row.label]));

const money = (value: number) => `${value < 0 ? "-" : ""}$${Math.abs(value)}k`;

const fill = (row: (typeof data)[number]) =>
  row.kind !== "delta" ? "#733bff" : (row.value ?? 0) < 0 ? "#e11d48" : "#16a34a";

export default function CashFlowChart() {
  return (
    <WaterfallChart
      data={data}
      config={config}
      animate
      margin={{ right: 16 }}
      aria-label="Quarterly cash flow, in thousands of dollars"
    >
      <WaterfallChart.Grid vertical={false} />
      <WaterfallChart.XAxis dataKey="id" tickFormatter={(id) => labels.get(id) ?? id} />
      <WaterfallChart.YAxis width={40} />
      <WaterfallChart.Connectors data={data} />
      <WaterfallChart.Series radius={3}>
        {data.map((row) => (
          <Cell key={row.id} fill={fill(row)} />
        ))}
      </WaterfallChart.Series>
      <WaterfallChart.Tooltip
        labelFormatter={(id) => labels.get(String(id)) ?? id}
        formatter={(_value, _name, entry) => money(entry.payload.value)}
      />
    </WaterfallChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/waterfall-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
WaterfallChart
├── WaterfallChart.Background
├── WaterfallChart.Grid
├── WaterfallChart.XAxis
├── WaterfallChart.YAxis
├── WaterfallChart.Connectors
├── WaterfallChart.Series
│   └── WaterfallChart.Labels
├── WaterfallChart.Tooltip
├── WaterfallChart.Legend
└── WaterfallChart.Content
```

`WaterfallChart` holds the rows, the series config and the accessible name, and draws only the parts you add. `WaterfallChart.Series` draws one floating bar per row, and `WaterfallChart.Connectors` draws the dashed lines that join each bar to the next. Add the connectors before the series so the bars sit on top. `WaterfallChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Steps [#steps]

Describe each step as an entry with a unique `id`, a `label` and a `kind`, then pass them through `computeWaterfallData` to get the rows the chart draws:

| `kind` | `value` | Bar |
| --- | --- | --- |
| `"start"` | The opening balance | From zero to the balance |
| `"delta"` | A signed change | From the previous balance to the new one |
| `"subtotal"` | None | From zero to the running balance |
| `"total"`, `"end"` | A balance you know | From zero to that balance |

`"total"` and `"end"` set the balance to the value you give; the chart never sums the steps into a total for you. Each row keeps its `value`, and adds the `start` and `balance` you can read in a tooltip or color by. Color increases and decreases with `Cell`, as in the example. Duplicate ids, values that aren't finite or `null`, and sums too large to represent throw.

Set `layout="vertical"` for horizontal bars, with the number scale on `WaterfallChart.XAxis` and the row ids on `WaterfallChart.YAxis`. The connectors follow.

Set `material="clay"` or `"glow"` on the series for a finish; see [Materials](../guides/materials.mdx).

### Missing Values [#missing-values]

A `null` change leaves its bar out and makes the balance unknown, so the bars after it disappear too, until a `"total"` or `"end"` gives a known balance again. The default tooltip skips steps without a bar; pass your own `content` to describe them. A change of `0` keeps its step with a zero-height bar.

### Connectors [#connectors]

`WaterfallChart.Connectors` takes the same `data` as the chart and joins two bars only when the balance carries over between them. They take Recharts' [ReferenceLine](https://recharts.github.io/en-US/api/ReferenceLine/) props, like `stroke` and `strokeDasharray`. If you hide the series with `hide`, pass the same `hide` to the connectors.

### Motion and Loading [#motion-and-loading]

Set `animate` to grow the bars from zero when the chart mounts. When the reader prefers reduced motion, bars appear without growing. See [Motion](../guides/motion.mdx).

Set `loading` while the data is on its way. The chart keeps its size and shows a placeholder, and screen readers hear `loadingLabel` ("Loading chart" by default):

```tsx
<WaterfallChart loading={isPending} loadingLabel="Loading cash flow" {...props}>
```

## API Reference [#api-reference]

### WaterfallChart [#waterfallchart]

### WaterfallChartOptions

| Prop               | Type                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data?`            | `ChartData<unknown> \| undefined`                                                                                                                                                                                                                    | The source data. Each element should be an object. The properties of each object represent the values of different data dimensions. Use the `dataKey` prop to specify which properties to use. |
| `config`           | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                                                                                                       |
| `emphasis?`        | `"auto" \| "none"`                                                                                                                                                                                                                                   | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"`                                                                                                |
| `interaction?`     | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                                                                                        |
| `aria-label?`      | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                                                                                                   |
| `aria-labelledby?` | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                                                                                          |
| `legendPosition?`  | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                                                                                            |
| `frameProps?`      | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                                                                                         |
| `animate?`         | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                              | Grows the bars from zero on mount. Pass options to change the duration or easing. Reduced motion skips it. Default: `false`                                                                    |
| `loading?`         | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                                                                                        |
| `loadingLabel?`    | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                                                                     |

### WaterfallChart.Connectors [#waterfallchartconnectors]

### WaterfallConnectorsOptions

| Prop         | Type                        | Description                                                               |
| ------------ | --------------------------- | ------------------------------------------------------------------------- |
| `data`       | `readonly WaterfallDatum[]` | The same rows you pass to the chart.                                      |
| `seriesKey?` | `string \| undefined`       | The series' key, so the connectors hide with the bars. Default: `"range"` |
| `hide?`      | `boolean \| undefined`      | Hides the connectors. Pass the same value as the series' `hide`.          |

<Caption>
`WaterfallChart.Series` takes the [BarChart.Series](./bar.mdx#barchartseries) props except `dataKey`, `data`, `stackId` and `minPointSize`; it always draws each row's `range`. `WaterfallChart` also takes every prop of Recharts' [BarChart](https://recharts.github.io/en-US/api/BarChart/), like `layout` and `margin`.
</Caption>