---
url: https://chartbuddy.io/embed/docs/chart-types/waterfall.md
---
# Waterfall

Running total that shows how contributions bridge two values.

## Identity

| | |
|---|---|
| `chartType` | `waterfall` |
| Option bag | `waterfall` |
| `seriesData` layout | `seriesRows` – row 0 = category header; later rows = series |
| Min grid | 2 rows × 2 columns (header included) |
| Orientation | Yes – `vertical` (default) or `horizontal` |
| Sample | [Waterfall](/samples/waterfall) |

***

## Minimal `chartData`

```js
{
  chartType: 'waterfall',
  isDataTransposed: true,
  seriesData: [
    ['', 'Start', 'Price', 'Volume', 'End'],
    ['Bridge', 100, 20, -10, null],
  ],
  waterfall: { columns: { 3: { isTotal: true } } },
  title: { visible: true, text: 'Bridge' },
  subtitle: { visible: false, text: '' },
}
```

***

## `seriesData`

Same `seriesRows` shape as bar/line (`isDataTransposed: true`). Leave **total** columns empty (`null`) – ChartBuddy computes them.

```js
[
  ['', 'Start', 'Price', 'Volume', 'End'],
  ['Bridge', 100, 20, -10, null], // End has no value of its own
]
```

Shared layout rules: [chartData schema · seriesData](/api/chart-data#seriesdata-layouts) · [Waterfall totals](/api/chart-data#waterfall-do-not-invent-totals).

***

## Option bag: `waterfall`

| Field | Default (new charts) | Role |
|---|---|---|
| `columns` | `{}` | Sparse per-column metadata (`isTotal`, `startBar`, `showSegments`) |
| `totalBarColor` | `'#808080'` | Color for total bars |
| `totalLegendLabel` | `'Total'` | Legend label for totals |
| `seriesStrokes` / `seriesStrokeWidths` | `[]` | Stroke chrome |
| `connectorOverrides` / `overrides` | `{}` | Connector / bar style patches |

### Do not invent totals

Contribution columns (default) add their value to the running total. Total columns (`isTotal: true`) **display** the running total and contribute nothing. Mark the column and leave its cell empty – a value typed there is ignored. Typing a closing figure **without** `isTotal` creates another contribution (the bridge then ends near ~2×).

### `waterfall.columns` keys

Keys are 0-based **data-column** indices: positions in the header row **after** the row-label cell.

```js
seriesData: [
  ['', 'Start', 'Price', 'Volume', 'Mix', 'End'],
  //  ^0       ^1       ^2        ^3     ^4   <- waterfall.columns keys
  ['Bridge', 100, 18, -8, 5, null],
],
waterfall: { columns: { 4: { isTotal: true } } },
```

`'End'` is header array index 5 but data column **4**. Off-by-one is silent.

| Property | Default | Meaning |
|---|---|---|
| `isTotal` | `false` | Show running total; ignore this column's own value |
| `startBar` | `false` | New sequence from zero; no connector from the previous column |
| `showSegments` | `false` | Draw a total as per-series segments instead of one solid bar |

### Column 0

Always forced to `isTotal` + `startBar`. Unlike other totals it **does** use its own value (opening balance).

### Multiple sequences

A mid-chart opening bar needs **both** `isTotal` and `startBar`:

```js
waterfall: {
  columns: {
    3: { isTotal: true },                 // close first bridge
    4: { isTotal: true, startBar: true }, // open second
  },
}
```

***

## Axes & scales

| Role | Vertical | Horizontal |
|---|---|---|
| Domain | `bottom` | `left` |
| Primary range | `left` | `bottom` |

Keep zero in play for readable bridges. Format the primary range side after orientation.

Details: [Axes · by chart type](/axes/by-chart-type).

***

## Type-specific behaviour

* Connectors and total chrome are easier to judge in the editor – then `getChartData()`.
* Palette: `legend.colors` (totals use `totalBarColor` / legend label).

***

## Pitfalls

* Closing value without `isTotal` (double-counts the bridge)
* Wrong column index (header position vs data-column index)
* `startBar` alone mid-chart (floating contribution instead of an opening total)
* Seeding sample totals into every new chart – leave `columns` sparse

***

## Related

* [chartData schema · waterfall](/api/chart-data#waterfall-do-not-invent-totals) · [Axes](/axes/)
* Sample: [Waterfall](/samples/waterfall)