Waterfall Charts: When They Earn Their Complexity

The first time I built a waterfall chart was in 2014 for an e-commerce market sizing deck. The client wanted to show how the Russian e-commerce market grew from one year to the next, and which underlying factors drove the change. We started with a bar chart. The bars showed the right numbers and answered exactly none of the actual questions, which were not “what was the market” but “what moved it.” We rebuilt it as a waterfall and the deck started to land.

That was nine years ago. I have built more waterfall charts since then, in Excel and Plotly and Tableau and once memorably in pure D3 because the deadline was tight and the chart library was not. Most of them were the right call. A handful were not. This is a guide to telling the difference, with a working Python implementation at the end.

What a waterfall actually shows

A waterfall chart shows a starting value, a sequence of additive changes, and an ending value. The bars are not the categories. The bars are the deltas. Every additional bar is one more factor in the explanation, and the chart’s visual job is to make the cumulative effect legible from left to right.

This is a small but important shift. A bar chart shows magnitudes. A line chart shows trends. A pie chart shows shares of a whole. A waterfall shows decomposition: how a single number got from where it was to where it ended up, broken into named pieces.

The four questions before reaching for a waterfall:

Are you trying to explain a change, not just show it? If the answer is “the market grew by 12 percent” and that is the whole story, a bar or line is enough. If the answer requires saying “the market grew by 12 percent, here is the math,” you want a waterfall.

Are the components additive? Waterfall math is sum-based. If your decomposition involves multiplication or ratios (cohort retention curves, for example), the waterfall lies. Pick a different chart.

Do you have a sensible left-to-right order? Waterfalls work because the eye reads them as a sequence. If the order is arbitrary, the chart becomes noise. Order by causal narrative (most upstream factor first) or by magnitude (largest first), but pick one and commit.

Is the audience comfortable with the convention? Waterfalls are a finance and consulting native. Engineering and product audiences sometimes need a sentence of explanation. That is fine, but plan for it.

If all four answers are yes, build the chart. If even one is no, find a different visualization.

The anatomy of a waterfall that earns its complexity

A good waterfall has five elements. Drop any of them and you slide back into a chart that looks intricate but does not communicate.

Intermediate floating bars, one per factor. Positive deltas float upward from the running total; negative deltas float downward. The vertical position of each bar tells the story; the height tells the magnitude.

Color encoding for direction. Green for positive, red for negative is the convention. You can swap to blue/orange if you are color-blind-aware, but pick one direction-of-change palette and use it everywhere in the deck. Mixed conventions across slides destroy reader confidence faster than any other dataviz sin.

A clearly labeled ending bar, also at full height, in a neutral or accent color that signals “this is the answer.” The ending bar’s height should be visually computable from the starting bar plus the sum of the intermediate deltas. If it is not, your data is wrong.

Connector lines between bars, dashed and subtle. These are easy to skip and the chart suffers without them. The lines do the work of telling the eye “the next bar starts here, not at the axis.” Without them, the chart reads as a stack of disconnected bars.

A sixth element, which not every audience needs but which I add by default for presentation contexts: numeric labels on every bar, with explicit signs on the deltas (“+70”, “-20”). The chart can carry one piece of information at a glance; the labels carry the precise math for the readers who want it.

A working implementation in Python

Plotly remains the cleanest Python library for waterfall charts as of 2023. It has a native go.Waterfall trace type that handles connectors and the absolute/relative/total measure types out of the box. The example below is the same e-commerce market story, rebuilt with anonymized numbers and US-market framing.

import plotly.graph_objects as go

labels = [
    "Q3 2022",
    "Inflation cooling",
    "Consumer spend recovery",
    "Marketplace expansion",
    "Tightened credit",
    "Currency headwind",
    "Q3 2023",
]

values = [820, 110, 70, 45, -30, -20, None]

measure = ["absolute", "relative", "relative",
           "relative", "relative", "relative", "total"]

text_labels = []
for i, v in enumerate(values):
    if v is None:
        text_labels.append(f"<b>${sum(x for x in values if x):,}M</b>")
    elif i == 0:
        text_labels.append(f"<b>${v:,}M</b>")
    else:
        sign = "+" if v > 0 else ""
        text_labels.append(f"{sign}{v}")

fig = go.Figure(go.Waterfall(
    x=labels,
    y=values,
    measure=measure,
    text=text_labels,
    textposition="outside",
    connector={"line": {"dash": "dot", "color": "rgba(120,120,120,0.6)"}},
    increasing={"marker": {"color": "#2ca02c"}},
    decreasing={"marker": {"color": "#d62728"}},
    totals={"marker": {"color": "#9467bd"}},
))

fig.update_layout(
    title="<b>US E-commerce GMV: Q3 2022 → Q3 2023</b>",
    yaxis_title="$M",
    showlegend=False,
    plot_bgcolor="white",
    xaxis={"tickangle": -45},
    height=500,
)
fig.show()

A few notes worth calling out about that code.

The measure array is doing structural work. The first bar is absolute (the starting value), the intermediate bars are relative (deltas added to the running total), and the last bar is total (a recomputed sum that Plotly draws as a clean bar without an arrow). Get this wrong and the chart breaks silently. If your ending bar floats at the wrong height, the measure column is the first place to look.

The text array is built manually because Plotly’s default labeling is too understated for presentation contexts. Putting the signs and dollar formatting in the labels at construction time saves a round of “can you make the labels bigger” feedback from the slide reviewer.

The colors here use the classic green/red/purple convention because the example is a finance-adjacent presentation. For a more modern look, swap in your design system’s positive/negative colors and use a neutral accent for the totals.

The dotted connector lines (dash="dot") are the visual element that does the most work for the least code. Skip them and the chart reads worse, by a surprising amount.

Common mistakes that flatten the chart

Missing totals. The chart shows the deltas but no starting and ending bars. The viewer is forced to do mental arithmetic to figure out what the magnitudes mean. Always include both endpoints; they are the reference frame for everything else.

Wrong sort order. The deltas are arranged alphabetically, or by the order they happened to appear in the source spreadsheet. The narrative arc disappears. Sort by magnitude (largest contributor first) or by causal sequence (the factor that drove the others first). Pick one rule and explain it in the caption if it is not visually obvious.

Reversed color encoding. Green for negative, red for positive, or worse, both colors used for both directions because the designer was matching a corporate palette. Direction-of-change colors are one of the few dataviz conventions strong enough to override brand palettes. Override them anyway. The chart’s job is to be read, not to look on-brand.

Connector lines turned off, or invisible at print resolution. The connectors are the visual glue. Without them the chart loses half its readability. Always test the chart at the resolution and contrast where it will be consumed. A waterfall that works on a 4K screen and falls apart in a printed deck is a waterfall that has not been reviewed properly.

A fifth mistake worth calling out is using a waterfall when you only have two or three components. At that scale, a sentence with the numbers in it does the same job in a tenth of the space. The waterfall earns its complexity when there are five to twelve components and the cumulative effect is the point. Two components is a sentence. Twelve components is a different chart.

When not to use a waterfall

Three situations where a waterfall is the wrong call.

When the metric is not additive. Conversion rates, retention curves, percentage shares: none of these decompose cleanly through addition. A waterfall on percent change is misleading because the deltas do not sum to the total in any meaningful sense.

When there are too many components. Past twelve to fifteen factors the chart turns into a fence and stops being readable. If your decomposition genuinely has that many factors, group them into themes and waterfall the themes. Or accept that the decomposition is too granular for any chart and use a table.

When the audience does not need decomposition. A waterfall costs the reader more cognitive effort than a bar chart, and the payoff is the breakdown. If the audience just needs to know that the number went up, build the bar. Save the waterfall for the moments where the breakdown is the story.

The honest summary

Waterfalls are a specialized tool. They earn their complexity when the answer to “what happened” requires a breakdown rather than a magnitude. Build them deliberately, with the five anatomy elements in place and the four mistakes deliberately avoided. The result is a chart that does work no other chart type can do.

A bar chart is the right answer ten times more often than a waterfall. That is fine. Reserve the waterfall for the one chart per deck that has to carry the decomposition story, and it will earn its keep every time.