> ## Documentation Index
> Fetch the complete documentation index at: https://prefab.prefect.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WaterfallChart

> Visualize how sequential increases and decreases build to a total.

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

> [card]
>
> ```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> from prefab_ui.components.charts import WaterfallChart
>
> data = [
>     {"label": "Revenue", "value": 42000},
>     {"label": "COGS", "value": -18000},
>     {"label": "Marketing", "value": -6500},
>     {"label": "R&D", "value": -8200},
>     {"label": "Other Income", "value": 3100},
> ]
>
> WaterfallChart(
>     data=data,
>     data_key="value",
>     name_key="label",
> )
> ```
>
> ```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> {
>   "view": {
>     "type": "WaterfallChart",
>     "data": [
>       {"label": "Revenue", "value": 42000},
>       {"label": "COGS", "value": -18000},
>       {"label": "Marketing", "value": -6500},
>       {"label": "R&D", "value": -8200},
>       {"label": "Other Income", "value": 3100}
>     ],
>     "dataKey": "value",
>     "nameKey": "label",
>     "height": 300,
>     "barRadius": 4,
>     "showConnectors": true,
>     "showLegend": true,
>     "showTooltip": true,
>     "animate": true,
>     "showGrid": true,
>     "showYAxis": true,
>     "valueFormat": "auto"
>   }
> }
> ```

## 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.

> [card]
>
> ```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> from prefab_ui.components.charts import WaterfallChart
>
> data = [
>     {"label": "Starting Cash", "value": 50000, "total": True},
>     {"label": "Sales", "value": 32000},
>     {"label": "Payroll", "value": -21000},
>     {"label": "Marketing", "value": -6500},
>     {"label": "Ending Cash", "value": 54500, "total": True},
> ]
>
> WaterfallChart(
>     data=data,
>     data_key="value",
>     name_key="label",
>     total_key="total",
> )
> ```
>
> ```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> {
>   "view": {
>     "type": "WaterfallChart",
>     "data": [
>       {"label": "Starting Cash", "value": 50000, "total": true},
>       {"label": "Sales", "value": 32000},
>       {"label": "Payroll", "value": -21000},
>       {"label": "Marketing", "value": -6500},
>       {"label": "Ending Cash", "value": 54500, "total": true}
>     ],
>     "dataKey": "value",
>     "nameKey": "label",
>     "totalKey": "total",
>     "height": 300,
>     "barRadius": 4,
>     "showConnectors": true,
>     "showLegend": true,
>     "showTooltip": true,
>     "animate": true,
>     "showGrid": true,
>     "showYAxis": true,
>     "valueFormat": "auto"
>   }
> }
> ```

## 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.

> [card]
>
> ```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> WaterfallChart(
>     data=data,
>     data_key="value",
>     name_key="label",
>     total_key="total",
>     show_connectors=False,
> )
> ```
>
> ```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> {
>   "view": {
>     "type": "WaterfallChart",
>     "data": [
>       {"label": "Starting Cash", "value": 50000, "total": true},
>       {"label": "Sales", "value": 32000},
>       {"label": "Payroll", "value": -21000},
>       {"label": "Marketing", "value": -6500},
>       {"label": "Ending Cash", "value": 54500, "total": true}
>     ],
>     "dataKey": "value",
>     "nameKey": "label",
>     "totalKey": "total",
>     "height": 300,
>     "barRadius": 4,
>     "showConnectors": false,
>     "showLegend": true,
>     "showTooltip": true,
>     "animate": true,
>     "showGrid": true,
>     "showYAxis": true,
>     "valueFormat": "auto"
>   }
> }
> ```

## 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.

> [card]
>
> ```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> WaterfallChart(
>     data=data,
>     data_key="value",
>     name_key="label",
>     total_key="total",
>     increase_color="#0ea5e9",
>     decrease_color="#f97316",
>     total_color="#64748b",
> )
> ```
>
> ```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> {
>   "view": {
>     "type": "WaterfallChart",
>     "data": [
>       {"label": "Starting Cash", "value": 50000, "total": true},
>       {"label": "Sales", "value": 32000},
>       {"label": "Payroll", "value": -21000},
>       {"label": "Marketing", "value": -6500},
>       {"label": "Ending Cash", "value": 54500, "total": true}
>     ],
>     "dataKey": "value",
>     "nameKey": "label",
>     "totalKey": "total",
>     "height": 300,
>     "increaseColor": "#0ea5e9",
>     "decreaseColor": "#f97316",
>     "totalColor": "#64748b",
>     "barRadius": 4,
>     "showConnectors": true,
>     "showLegend": true,
>     "showTooltip": true,
>     "animate": true,
>     "showGrid": true,
>     "showYAxis": true,
>     "valueFormat": "auto"
>   }
> }
> ```

## Value Formatting

Use `value_format` to format numeric values on the value axis and in tooltips, same as every other chart. See [Charts](https://prefab.prefect.io/docs/components/charts.md#formatting-values) for the full set of pipe strings.

> [card]
>
> ```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> from prefab_ui.components.charts import WaterfallChart
>
> data = [
>     {"label": "Starting Cash", "value": 50000, "total": True},
>     {"label": "Sales", "value": 32000},
>     {"label": "Payroll", "value": -21000},
>     {"label": "Marketing", "value": -6500},
>     {"label": "Ending Cash", "value": 54500, "total": True},
> ]
>
> WaterfallChart(
>     data=data,
>     data_key="value",
>     name_key="label",
>     total_key="total",
>     value_format="currency:0",
> )
> ```
>
> ```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
> {
>   "view": {
>     "type": "WaterfallChart",
>     "data": [
>       {"label": "Starting Cash", "value": 50000, "total": true},
>       {"label": "Sales", "value": 32000},
>       {"label": "Payroll", "value": -21000},
>       {"label": "Marketing", "value": -6500},
>       {"label": "Ending Cash", "value": 54500, "total": true}
>     ],
>     "dataKey": "value",
>     "nameKey": "label",
>     "totalKey": "total",
>     "height": 300,
>     "barRadius": 4,
>     "showConnectors": true,
>     "showLegend": true,
>     "showTooltip": true,
>     "animate": true,
>     "showGrid": true,
>     "showYAxis": true,
>     "valueFormat": "currency:0"
>   }
> }
> ```

## API Reference

> [card] WaterfallChart Parameters
>
> **data** `list[dict] | str` *required*
>
> Data as a list of dicts, or a `{{ field }}` interpolation reference.
>
> **data\_key** `str` *required*
>
> Data key for each row's value. Positive values increase the running total, negative values decrease it.
>
> **name\_key** `str` *required*
>
> Data key for bar labels.
>
> **total\_key** `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.
>
> **height** `int` (default: 300)
>
> Chart height in pixels.
>
> **increase\_color** `str | None` (default: None)
>
> CSS color for increase bars. Defaults to the theme's success color.
>
> **decrease\_color** `str | None` (default: None)
>
> CSS color for decrease bars. Defaults to the theme's destructive color.
>
> **total\_color** `str | None` (default: None)
>
> CSS color for total bars. Defaults to the theme's info color.
>
> **bar\_radius** `int` (default: 4)
>
> Corner radius of each bar in pixels.
>
> **show\_connectors** `bool` (default: True)
>
> Show dashed bridge lines connecting each bar's ending height to the next bar.
>
> **show\_legend** `bool` (default: True)
>
> Show a legend of the increase/decrease/total categories present in the data.
>
> **show\_tooltip** `bool` (default: True)
>
> Show tooltips on hover.
>
> **animate** `bool` (default: True)
>
> Animate data changes. Reactive data defaults to `False`; set `animate=True`
> explicitly to opt in.
>
> **show\_grid** `bool` (default: True)
>
> Show horizontal grid lines.
>
> **show\_y\_axis** `bool` (default: True)
>
> Show the y-axis with its tick labels.
>
> **value\_format** `str` (default: "auto")
>
> Format value-axis ticks and tooltip values with an expression pipe such as `currency`, `currency:EUR`, `percent:1`, or `compact:0`.
>
> **css\_class** `str | None` (default: None)
>
> Additional Tailwind CSS classes.

## Protocol Reference

```json WaterfallChart theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "type": "WaterfallChart",
  "id?": "string",
  "onMount?": "any",
  "data": "object[] | string (required)",
  "dataKey": "string (required)",
  "nameKey": "string (required)",
  "totalKey?": "string",
  "height?": "300",
  "increaseColor?": "string",
  "decreaseColor?": "string",
  "totalColor?": "string",
  "barRadius?": 4,
  "showConnectors?": true,
  "showLegend?": true,
  "showTooltip?": true,
  "animate?": true,
  "showGrid?": true,
  "showYAxis?": true,
  "valueFormat?": "string",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [WaterfallChart](https://prefab.prefect.io/docs/protocol/waterfall-chart.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.