Plotly · Class

go.Waterfall

A Plotly graph-object trace for visualizing how positive and negative contributions build to totals in a waterfall chart. Vertical charts use y for values and x for labels by default.

How it works

Constructs a waterfall trace whose bars show how positive or negative contributions change a running total. With the default vertical orientation, values come from y and category labels from x; horizontal orientation swaps those roles.

Syntax

plotly.graph_objects.Waterfall(arg=None, alignmentgroup=None, base=None, cliponaxis=None, connector=None, customdata=None, decreasing=None, dx=None, dy=None, hoverinfo=None, hoverlabel=None, hovertemplate=None, hovertext=None, ids=None, increasing=None, legend=None, legendgroup=None, legendgrouptitle=None, legendrank=None, legendwidth=None, measure=None, meta=None, name=None, offset=None, offsetgroup=None, opacity=None, orientation=None, selectedpoints=None, showlegend=None, stream=None, text=None, textfont=None, textposition=None, totals=None, visible=None, width=None, x=None, x0=None, xaxis=None, xhoverformat=None, xperiod=None, xperiod0=None, xperiodalignment=None, y=None, y0=None, yaxis=None, yhoverformat=None, yperiod=None, yperiod0=None, yperiodalignment=None, zorder=None, **kwargs)

Parameters

Name	Type	Description
`orientation`	`str`	Controls whether the trace is vertical or horizontal; the default is vertical.
`y`	`array-like`	Values that determine the span of the bars for vertical orientation.
`x`	`array-like`	Category labels for vertical orientation.
`measure`	`array-like`	Classifies bars, such as relative changes or totals.

Returns

A plotly.graph_objects.Waterfall trace object.

Key points

Instantiate plotly.graph_objects.Waterfall to create the trace object.
The trace visualizes how individual positive or negative elements contribute to a result.
For the default vertical orientation, y supplies the bar magnitudes.
For vertical charts, x supplies the category labels.
Use horizontal orientation when the categories should run along the vertical axis and values along the horizontal axis.

Common mistakes

For vertical traces, provide the bar values through y; changing orientation to horizontal makes x the value axis.
Horizontal orientation reverses the usual x/y roles, so labels and magnitudes must be supplied accordingly.

Example: Basic waterfall chart

import plotly.graph_objects as go

fig = go.Figure(go.Waterfall(
    measure=["relative", "relative", "total"],
    x=["Sales", "Costs", "Profit"],
    y=[100, -40, 0],
    textposition="outside"
))
fig.show()

Creates a vertical waterfall trace with two relative changes and a computed total.

When to use it

Show how revenue, costs, and adjustments produce profit.

Financial reporting

Explain the cumulative effect of increases and decreases against a starting budget.

Budget analysis

Break down how sequential gains and losses produce a final KPI.

Operational metrics

Interview questions

QWhat is a Waterfall trace used for?

Waterfall is a graph-object trace for displaying positive or negative contributions in a bar chart. In the default vertical mode, y contains the values and x contains the labels.

Follow-up: How would you make the same chart horizontal? Set orientation to "h" and interchange the roles of x and y.

QHow do you construct a basic waterfall chart in Python?

Use go.Figure(go.Waterfall(...)) to create a figure containing the trace. The measure array can classify entries such as relative changes and totals, while x and y provide category labels and values.

Follow-up: How can totals be represented? Include an appropriate total entry in measure and provide its category label; the trace computes the total bar.

QWhat changes when orientation is set to horizontal?

The orientation property defaults to vertical, where the span of the bars is determined by y and labels are supplied in x. Setting orientation to h interchanges those data roles.

Follow-up: What should be checked when converting a vertical chart? Ensure the values and labels are moved to the axes expected by the selected orientation.

plotly.graph_objects.Figure
plotly.graph_objects.Figure.add_trace
waterfall trace reference

Source: plotly.graph_objects.Waterfall — 6.8.0 documentation. Checked 2026-10-15.