excel chart waterfall

Excel: Chart - waterfall

A dedicated page for the waterfall chart type. Waterfall charts (also called bridge charts) show how an initial value is affected by a series of positive and negative changes, ending with a cumulative total. Common in financial P&L presentations.

Path: /{SheetName}/chart[N]

Add command shape:

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=waterfall \
  --prop title="P&L Waterfall" \
  --prop data="Flow:Start:1000,Revenue:500,Costs:-300,Tax:-100,Net:1100" \
  --prop increaseColor=70AD47 \
  --prop decreaseColor=FF0000 \
  --prop totalColor=4472C4 \
  <styling props>

See also: Chart - add, Chart - set.

Chart type variants

Type string	Aliases
waterfall	wf

Waterfall-specific properties

Colors

Property	Default	Notes
increaseColor	4472C4 (blue)	Color for positive change bars
decreaseColor	FF0000 (red)	Color for negative change bars
totalColor	2E75B6 (dark blue)	Color for the cumulative total bar

Total bar

Property	Default	Notes
waterfallTotal	true	Show cumulative total as the last bar

When true, the last data point is recomputed as the cumulative sum and rendered with totalColor.

Data format

Waterfall data uses a special Tag:Value format to mark totals and subtotals:

Name:Start:1000,Revenue:500,Costs:-300,Tax:-100,Net:1100

• The first value is the starting point
• Intermediate values are deltas (positive = increase, negative = decrease)
• The last value is the cumulative total (auto-calculated when waterfallTotal=true)

Examples

# Basic P&L waterfall
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=waterfall \
  --prop title="P&L Waterfall" \
  --prop data="Flow:Start:1000,Revenue:500,Costs:-300,Tax:-100,Net:1100" \
  --prop increaseColor=70AD47 \
  --prop decreaseColor=FF0000 \
  --prop totalColor=4472C4

# Minimal waterfall (auto total)
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=waterfall \
  --prop title="Budget Changes" \
  --prop data="Budget:Base:50000,New Hires:12000,Equipment:-3000,Training:-2000,Total:57000"

Implementation details

Waterfall charts are implemented as stacked bar charts with 3 series:

1. Base (invisible) - running total baseline with no fill
2. Increase (visible) - positive change bars
3. Decrease (visible) - negative change bars

The "floating bar" effect is achieved by the invisible base series pushing the visible bars to the correct vertical position. Default gapWidth=80 and overlap=100 for a connected appearance.

Title styling

Property	Default	Notes
title	—	Chart title text
title.font / titleFont	—	Font family
title.size / titleSize	—	Font size (pt)
title.color / titleColor	—	Font color (hex)
title.bold / titleBold	—	Bold (true/false)
title.glow / titleGlow	—	Glow: "COLOR-RADIUS-OPACITY" or "none"
title.shadow / titleShadow	—	Shadow: "COLOR-BLUR-ANGLE-DIST-OPACITY" or "none"

Legend

Property	Default	Notes
legend	true	Position: top, bottom, left, right, none
legend.overlay	false	Float legend on top of the chart
legendFont / legend.font	—	"size:color:fontname"

Axis features

Scale control

Property	Default	Notes
axisMin / min	(auto)	Value axis lower bound
axisMax / max	(auto)	Value axis upper bound
majorUnit	(auto)	Major gridline / tick interval
minorUnit	(auto)	Minor gridline / tick interval
axisNumFmt / axisNumberFormat	General	Number format for tick labels (e.g. "$#,##0", "0%")

# Lock Y axis range for P&L
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=waterfall \
  --prop title="P&L Waterfall" \
  --prop data="Flow:Start:1000,Revenue:500,Costs:-300,Tax:-100,Net:1100" \
  --prop axisMin=0 --prop axisMax=2000 --prop majorUnit=200

Logarithmic scale

Property	Default	Notes
logBase / logScale	—	Logarithmic scale base (e.g. 10)

Reversed axis

Property	Default	Notes
axisOrientation / axisReverse	minMax	Set to maxMin or true to flip the Y axis

Display units

Property	Default	Notes
dispUnits / displayUnits	—	thousands, millions, billions, etc.

Axis visibility and styling

Property	Default	Notes
axisVisible / axis.visible	true	Show/hide both axes
axisLine / axis.line	—	Value axis line: "color:width:dash"
catAxisLine	—	Category axis line: "color:width:dash"
majorTickMark / majorTick	—	out, in, cross, none
minorTickMark / minorTick	—	Same as major tick
tickLabelPos	nextTo	nextTo, high, low, none

Gridlines

Property	Default	Notes
gridlines / majorGridlines	true	Toggle or configure: true, false/none, or "color:widthPt:dash"
minorGridlines	false	Same format as gridlines

# Subtle gridlines for waterfall
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=waterfall \
  --prop title="P&L Waterfall" \
  --prop data="Flow:Start:1000,Revenue:500,Costs:-300,Tax:-100,Net:1100" \
  --prop "gridlines=E5E7EB:0.5:solid" \
  --prop "minorGridlines=F3F4F6:0.3:sysDot"

Fills and borders

Property	Default	Notes
plotFill / plotAreaFill	—	Plot area background: hex, gradient "C1-C2[:angle]", or "none"
chartFill / chartAreaFill	—	Chart area background
plotArea.border / plotBorder	—	Plot area outline: "color:width:dash" or "none"
chartArea.border / chartBorder	—	Chart area outline

Series shadow and outline

Property	Default	Notes
series.shadow / seriesShadow	—	"COLOR-BLUR-ANGLE-DIST-OPACITY" or "none"
series.outline / seriesOutline	—	"COLOR-WIDTH" e.g. "FFFFFF-0.5" or "none"

Data labels

Property	Default	Notes
dataLabels	false	Toggle data labels
labelPos / labelPosition	—	Position: center, insideEnd, insideBase, outsideEnd, top, bottom, left, right, bestFit
labelFont	—	"size:color:bold"
dataLabel{N}.text	—	Custom text for individual label
dataLabel{N}.x/y/w/h	—	Manual layout of individual label
dataLabel{N}.delete	—	Hide individual label
dataLabels.separator	—	Separator between label parts
dataLabels.numFmt	—	Number format for labels

Transparency and opacity

Property	Default	Notes
transparency	0	Series transparency (0-100%)
opacity / alpha	100	Series opacity (0-100%)

Layout control

Property	Default	Notes
x, y	0	Chart position (column/row index)
width	8	Chart width (column units)
height	15	Chart height (row units)
plotArea.x/y/w/h	—	Manual plot area layout (0-1 decimal)
title.x/y/w/h	—	Manual title layout
legend.x/y/w/h	—	Manual legend layout

Display blanks

Property	Default	Notes
dispBlanksAs / blanksAs	gap	How blank cells are handled: gap, zero, span/connect

Conditional coloring

Property	Default	Notes
colorRule / conditionalColor	—	Color data points conditionally
point{N}.color	—	Individual data point color (hex)

Full example: presentation-grade waterfall chart

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=waterfall \
  --prop title="FY2024 P&L Bridge" \
  --prop title.size=14 --prop title.bold=true \
  --prop title.font="Arial" --prop title.color=1F2937 \
  --prop data="Flow:Start:1000,Revenue:500,Services:200,COGS:-300,OpEx:-150,Tax:-100,Net:1150" \
  --prop increaseColor=70AD47 \
  --prop decreaseColor=ED7D31 \
  --prop totalColor=4472C4 \
  --prop dataLabels=true --prop labelPos=outsideEnd \
  --prop "labelFont=9:6B7280:true" \
  --prop "gridlines=E5E7EB:0.5:solid" \
  --prop "axisNumFmt=$#,##0" \
  --prop plotFill=FAFBFC \
  --prop legend=bottom \
  --prop "legendfont=9:6B7280:Arial" \
  --prop x=0 --prop y=0 --prop width=14 --prop height=20

HTML preview support

Feature	Preview	Notes
Floating bars	Yes	Via stacked column rendering
Increase/decrease colors	Yes
Total bar color	Yes
Data labels	Yes	Value text near bars
Custom axis scale	Yes	axisMin/axisMax/majorUnit
Gridlines	Yes	Color, width, dash from OOXML
Shadow effects	No	Decorative; not rendered
Glow effects	No	Decorative; not rendered

Known quirks

• Colors are set at creation only. increaseColor, decreaseColor, and totalColor are applied during add; there is no dedicated setter to change them after creation (use point{N}.color instead).
• Detection pattern: officecli identifies waterfall charts by checking for a stacked bar with 3 series where the first is named "Base" with no fill.

Inspect an existing waterfall chart

# List all charts
officecli query data.xlsx chart

# Inspect a specific chart
officecli get data.xlsx "/Sheet1/chart[1]"

# Render to HTML preview
officecli view data.xlsx html > preview.html

See Also

• Chart - Overview of chart operations
• Chart add - Generic chart add (all types)
• Chart set - Modify existing charts
• Chart get - Read back chart properties
• Column/bar chart - Underlying rendering

---

Based on OfficeCLI v1.0.64