Skip to main content
WaterfallChart renders a sequence of values as floating bars, each one starting where the previous bar ended. It’s the standard shape for showing how a series of gains and losses roll up into a running total — a profit bridge, a cash flow breakdown, a headcount change over a quarter. Bars are colored automatically: increases, decreases, and totals each get their own color, and dashed “bridge” lines connect one bar to the next. Like PieChart and RadialChart, WaterfallChart doesn’t use ChartSeries — instead data_key names the value field and name_key names the label field, since there’s only ever one series of floating bars.

​
Basic Usage

​
Totals

Mark a row as a total with total_key — a boolean field on each row. Total bars draw from zero instead of stacking on the running total, and they reset the running total for the rows that follow. This is how a waterfall shows a starting balance, a series of changes, and an ending balance in one chart.

​
Hiding Bridges

Bridge lines connecting each bar’s ending height to the next bar are on by default. Set show_connectors=False to drop them for a cleaner, more compact read.

​
Custom Colors

Override the automatic increase/decrease/total colors with increase_color, decrease_color, and total_color. Each accepts any CSS color or theme variable.

​
Value Formatting

Use value_format to format numeric values on the value axis and in tooltips, same as every other chart. See Charts for the full set of pipe strings.

​
API Reference

WaterfallChart Parameters

​
list[dict] | str
required
Data as a list of dicts, or a {{ field }} interpolation reference.
​
str
required
Data key for each row’s value. Positive values increase the running total, negative values decrease it.
​
str
required
Data key for bar labels.
​
str | None
default:"None"
Data key marking a row as a total (bool). Total bars are drawn from zero instead of stacking on the running total, and reset it for subsequent rows.
​
int
default:"300"
Chart height in pixels.
​
str | None
default:"None"
CSS color for increase bars. Defaults to the theme’s success color.
​
str | None
default:"None"
CSS color for decrease bars. Defaults to the theme’s destructive color.
​
str | None
default:"None"
CSS color for total bars. Defaults to the theme’s info color.
​
int
default:"4"
Corner radius of each bar in pixels.
​
bool
default:"True"
Show dashed bridge lines connecting each bar’s ending height to the next bar.
​
bool
default:"True"
Show a legend of the increase/decrease/total categories present in the data.
​
bool
default:"True"
Show tooltips on hover.
​
bool
default:"True"
Animate data changes. Reactive data defaults to False; set animate=True explicitly to opt in.
​
bool
default:"True"
Show horizontal grid lines.
​
bool
default:"True"
Show the y-axis with its tick labels.
​
str
default:"\"auto\""
Format value-axis ticks and tooltip values with an expression pipe such as currency, currency:EUR, percent:1, or compact:0.
​
str | None
default:"None"
Additional Tailwind CSS classes.

​
Protocol Reference

WaterfallChart
For the complete protocol schema, see WaterfallChart.