# WaterfallChart

How a total got from one figure to another.

- Group: Charts
- Import: `import { WaterfallChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/waterfall-chart/
- Related: bar-chart, funnel-chart

## When to reach for it

“Why did this change”, where the contributions can be negative. A pie cannot hold a negative slice; a BarChart is right when the parts need not add up to the gap between two totals.

## Accessibility

- The connectors draw the steps as a sequence, and most breakdowns are not sequential — churn and expansion in the same month are simultaneous, and a reader takes the leftmost bar as the first cause. Where the order is arbitrary, say so in description.
- Intermediate bars are floating lengths read against no baseline, so a small step high up the cascade is hard to compare with a large one near zero. Total bars sit on the axis and are the only ones a reader can read absolutely.
- Direction is carried by the label’s sign and the bar’s texture as well as its position, so the reading survives greyscale and forced colours.
- A closing bar with no value is computed from the deltas, which keeps the arithmetic in the data rather than in the caller’s head.

## WaterfallChart

How a total got from one figure to another — an opening balance, the signed contributions that moved it, and where it closed. The form for "why did this change", which a pair of bars cannot answer and a pie chart answers wrongly, because contributions can be NEGATIVE and a slice cannot. Reach for `<BarChart>` when the parts do not have to add up to the gap between two totals, and for `<FunnelChart>` when the quantity only ever shrinks. **The connectors are the claim to be careful about.** They draw the steps as a sequence — this happened, then this — and most breakdowns are not sequential at all: churn and expansion in the same month are simultaneous, and the order they are listed in is an editorial choice. The arithmetic survives any order; the STORY does not, and a reader will take the leftmost bar as the first cause. Two related traps: the intermediate bars are floating lengths read against no baseline, so a small step high up the cascade is hard to compare with a large one near zero; and any step that is itself a net of two larger opposing movements is invisible as such. Where the order is arbitrary, say so in the `description`. Recharts earns its place for the axes, grid and tooltip. Each bar is a floating range — from the running total to the new one — with a custom shape over it, because Recharts has no waterfall mark and the connectors have to be drawn from the same geometry as the bars they join.

### Props

- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a waterfall has one quantity and as many bars as it has steps.
- `data` (required) — `WaterfallStep[]`. The steps, in the order they are applied. Order is the arithmetic: the chart does not sort, because a different order is a different total at every intermediate bar.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<WaterfallChart.Bars>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints — ticks, labels, tooltip, table.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { WaterfallChart, formatNumber, type WaterfallStep } from '@misoto22/design/charts'

<WaterfallChart
  title="ARR bridge, FY24 to FY25"
  showTitle
  description="Thousands of AUD. The steps are simultaneous; the order is editorial."
  data={steps}
  formatValue={formatNumber({ style: 'compact' })}
>
  <WaterfallChart.Grid />
  <WaterfallChart.XAxis />
  <WaterfallChart.YAxis />
  <WaterfallChart.Tooltip />
  <WaterfallChart.Bars showValues />
</WaterfallChart>
```

## Example — subtotals

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { WaterfallChart, formatNumber, type WaterfallStep } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={connectors ? 'joined' : 'loose'}
    onValueChange={(next) => next && setConnectors(next === 'joined')}
    aria-label="Connectors"
  >
    <ToggleGroupItem value="joined">connectors</ToggleGroupItem>
    <ToggleGroupItem value="loose">bars only</ToggleGroupItem>
  </ToggleGroup>

  <WaterfallChart
    title="Operating profit bridge"
    data={steps}
    formatValue={formatNumber({ style: 'compact' })}
  >
    <WaterfallChart.Grid />
    <WaterfallChart.XAxis />
    <WaterfallChart.YAxis />
    <WaterfallChart.Tooltip />
    <WaterfallChart.Bars connectors={connectors} showValues />
  </WaterfallChart>
</div>
```