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

---

Minimal chartData

{
  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.

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

Shared layout rules: chartData schema · seriesData · Waterfall 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.

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:

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.

---

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 · Axes
• Sample: Waterfall