waterfall_chart: Create an interactive waterfall chart.

In ddplot: Create D3 Based SVG Graphics

Create an interactive waterfall chart.

Description

A waterfall chart shows how an initial value is built up or eroded by a series of positive and negative contributions to reach a final total. Each bar starts exactly where the previous one ended, making cumulative effects immediately visible. It is the standard chart for P&L decomposition, budget variance analysis, and any "what changed and why" narrative.

Hovering over a bar shows a tooltip with the label, the delta value, and the running total at that point.

Usage

waterfall_chart(
  data,
  x,
  y,
  measure = NULL,
  positiveColor = "#4CAF50",
  negativeColor = "#F44336",
  totalColor = "#5C85D6",
  connector = TRUE,
  connectorColor = "#aaaaaa",
  showLabels = TRUE,
  labelFontSize = 10,
  title = NULL,
  titleFontSize = 16,
  xtitle = NULL,
  xtitleFontSize = 13,
  ytitle = NULL,
  ytitleFontSize = 13,
  xFontSize = 11,
  yFontSize = 11,
  opacity = 1,
  font = "Verdana, Geneva, Tahoma, sans-serif",
  bgcol = "white",
  axisCol = "black",
  width = NULL,
  height = NULL
)

Arguments

data	The data frame containing the variables to consider.
x	The name of the column containing category labels.
y	The name of the column containing the delta values (positive for increases, negative for decreases).
measure	Optional. The name of a column that classifies each row as "relative" (default — a delta added to the running total) or "total" (a bar spanning from zero to the current running total, used for subtotals and the final total).
positiveColor	Fill color for bars representing an increase. Defaults to "#4CAF50".
negativeColor	Fill color for bars representing a decrease. Defaults to "#F44336".
totalColor	Fill color for "total" measure bars. Defaults to "#5C85D6".
connector	Logical. Whether to draw dashed connector lines between consecutive bars. Defaults to TRUE.
connectorColor	Color of the connector lines. Defaults to "#aaaaaa".
showLabels	Logical. Whether to display the delta value above or below each bar. Defaults to TRUE.
labelFontSize	Font size of the bar value labels. Defaults to 10.
title	Optional. Title of the chart.
titleFontSize	Font size of the chart title. Defaults to 16.
xtitle	Optional. Title of the x-axis.
xtitleFontSize	Font size of the x-axis title. Defaults to 13.
ytitle	Optional. Title of the y-axis.
ytitleFontSize	Font size of the y-axis title. Defaults to 13.
xFontSize	Font size of the x-axis tick labels. Defaults to 11.
yFontSize	Font size of the y-axis tick labels. Defaults to 11.
opacity	Opacity of the bars (0 to 1). Defaults to 1.
font	The font family used for all text. Defaults to "Verdana, Geneva, Tahoma, sans-serif".
bgcol	Background color of the SVG. Defaults to "white".
axisCol	Color of axis lines, ticks, and labels. Defaults to "black".
width	Optional. The width of the SVG output.
height	Optional. The height of the SVG output.

Value

An interactive SVG waterfall chart.

Examples

# P&L bridge: from revenue down to net income
pnl <- data.frame(
  label   = c("Revenue", "COGS", "Gross Profit",
              "R&D", "S&M", "G&A", "Operating Income"),
  value   = c(1200, -450, 750, -120, -90, -60, 480),
  measure = c("relative", "relative", "total",
              "relative", "relative", "relative", "total")
)

waterfall_chart(
  data    = pnl,
  x       = "label",
  y       = "value",
  measure = "measure",
  title   = "P&L bridge",
  ytitle  = "USD thousands"
)

# Monthly cash flow
cashflow <- data.frame(
  month = c("Jan", "Feb", "Mar", "Apr", "May", "Jun"),
  delta = c(120, -30, 80, -60, 95, -20)
)

waterfall_chart(
  data           = cashflow,
  x              = "month",
  y              = "delta",
  title          = "Monthly cash flow",
  ytitle         = "USD thousands",
  positiveColor  = "steelblue",
  negativeColor  = "tomato"
)

ddplot documentation built on Aug. 25, 2026, 5:10 p.m.