> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# Waterfall chart

> Show cumulative contributions to a total with the WaterfallChart component.

API reference: [WaterfallChart()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.waterfallchart/index.md) (function), [IWaterfallChartProps](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartprops/index.md) (interface)

A **waterfall chart** shows the cumulative impact of sequentially introduced positive or negative values. Use it for financial data such as profit and loss statements or budget analysis, or wherever you want to show how a starting value changes step by step.

![Waterfall chart where revenue items add up and cost items subtract, ending with a total column](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/waterfall_chart.png)

## [Buckets](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#buckets)

| Prop | Required | Takes | What it does |
| --- | --- | --- | --- |
| `measures` | Yes | One or more measures | With one measure, each `viewBy` value is a column. With more measures, each measure is a column. |
| `viewBy` | No | One attribute | Splits a single measure into one column per attribute value. Not used with multiple measures. |
| `filters` | No | Filters | Limits the data the chart shows. |

## [Sorting](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#sorting)

To sort the data, pass sort items in the `sortBy` prop. See [Sort items](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execution/execution-model/index.md#sort-items).

## [Configuration](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#configuration)

Pass these options in the `config` prop. See [Chart configuration](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/chart-config/index.md) for the shared options. The following example shows the `config` structure with sample values for waterfall charts:

```ts
import type { IChartConfig } from "@gooddata/sdk-ui-charts";

const config: IChartConfig = {
    colors: ["rgb(195, 49, 73)", "rgb(168, 194, 86)"],
    colorPalette: [{
        guid: "01",
        fill: {
            r: 195,
            g: 49,
            b: 73
        }
    }, {
        guid: "02",
        fill: {
            r: 168,
            g: 194,
            b: 86
        }
    }],
    colorMapping: [{
        // waterfall colors are assigned to the "total", "positive", and "negative" bars,
        // not to measures; the available ids are "properties.color.total",
        // "properties.color.positive", and "properties.color.negative"
        predicate: (headerItem) => {
            return headerItem.colorHeaderItem && (headerItem.colorHeaderItem.id === "properties.color.negative")
        },
        color: {
            type: "guid",
            value: "02"
        }
    }],
    legend: {
        enabled: true,
        position: "top",
    },
    dataLabels: {
        visible: "auto"
    },
    total: {
        enabled: true, // default; set to false to hide the computed total column
        name: "Total", // custom title of the computed total column
        measures: ["measure_localIdentifier"] // render these measures as total columns instead
    },
    separators: {
        thousand: ",",
        decimal: "."
    }
};
```

### [Total columns](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#total-columns)

The `total` option controls the total columns:

```ts
const config: IChartConfig = {
    total: {
        enabled: true,
        name: "Total",
        measures: ["revenue_total", "profit_total"]
    }
};
```

- `total.enabled` (default `true`) appends a computed total column that sums all the other columns. Set it to `false` to hide it.
- `total.name` sets the title of the computed total column. The default is the localized "Total".
- `total.measures` lists the local identifiers of measures that should be rendered as total columns (bars that start from zero) rather than as increments. This only makes sense with multiple measures. When `total.measures` is not empty, the computed total column is not added.

## [Usage patterns](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#usage-patterns)

A waterfall chart reads best with a small number of columns (typically 3 to 15) that represent sequential changes from a starting value to a final value.

### [Single measure with a viewBy attribute](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#single-measure-with-a-viewby-attribute)

When using a single measure with a `viewBy` attribute, each attribute value creates a column showing the incremental change. The chart appends a computed total column; use `total.enabled` and `total.name` to hide or rename it:

```tsx
<WaterfallChart
    measures={[Md.$MonthlyRevenue]}
    viewBy={Md.Month}
    config={{
        total: {
            name: "Yearly total"
        }
    }}
/>
```

### [Multiple measures](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#multiple-measures)

When using multiple measures, each measure creates a column in the waterfall. The `viewBy` attribute cannot be used in this case. `total.measures` takes the measures' local identifiers, so read them with `measureLocalId`:

```tsx
import { measureLocalId } from "@gooddata/sdk-model";

<WaterfallChart
    measures={[Md.$StartingBalance, Md.$Income, Md.$Expenses, Md.$EndingBalance]}
    config={{
        total: {
            measures: [measureLocalId(Md.$EndingBalance)]
        }
    }}
/>
```

### [With total columns](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#with-total-columns)

You can mark specific measures as totals so that they render as total columns instead of increments:

```tsx
import { newMeasure } from "@gooddata/sdk-model";

// Define a total measure with an explicit local identifier
const totalRevenue = newMeasure("total_revenue", (m) => m.title("Total Revenue").localId("total_revenue"));

<WaterfallChart
    measures={[Md.$Q1Revenue, Md.$Q2Revenue, Md.$Q3Revenue, Md.$Q4Revenue, totalRevenue]}
    config={{
        total: {
            measures: ["total_revenue"]
        }
    }}
/>
```

## [Structure](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#structure)

```tsx
import "@gooddata/sdk-ui-charts/styles/css/main.css";
import { WaterfallChart } from "@gooddata/sdk-ui-charts";

<WaterfallChart
    measures={<measures>}
    config={<chart-config>}
    …
/>
```

## [Example](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#example)

```tsx
import "@gooddata/sdk-ui-charts/styles/css/main.css";
import { WaterfallChart } from "@gooddata/sdk-ui-charts";
import * as Md from "./catalog.js";

const style = { height: 300 };

<div style={style}>
    <WaterfallChart
        measures={[Md.$Revenue]}
        viewBy={Md.Quarter}
    />
</div>
```

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/waterfall-chart/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`measures`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md#iwaterfallchartbucketpropsmeasures) | [`AttributesMeasuresOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributesmeasuresorplaceholders/index.md) | Yes | Specify one or more measures to segment the waterfall chart. | [`IWaterfallChartBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md) |
| [`backend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md#ibucketchartpropsbackend) | [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | No | Analytical backend, from which the chart will obtain data to visualize If you do not specify instance of analytical backend using this prop, then you MUST have BackendProvider up in the component tree. | [`IBucketChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md) |
| [`config`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropsconfig) | [`IChartConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ichartconfig/index.md) | No | Configure chart's behavior and appearance. | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`drillableItems`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropsdrillableitems) | [`ExplicitDrill`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.explicitdrill/index.md)`[]` | No | Configure drillability; e.g. which parts of the visualization can be interacted with. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropserrorcomponent) | `ComponentType<`[`IErrorProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ierrorprops/index.md)`>` | No | React component to display in the event when there is an error with either obtaining the data from backend or with the data itself. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`execConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropsexecconfig) | [`IExecutionConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iexecutionconfig/index.md) | No | Execution configuration, will provide the execution with necessary config before initiating execution. | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`exportTitle`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropsexporttitle) | `string` | No | Set title to use for exported files. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`filters`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md#iwaterfallchartbucketpropsfilters) | [`NullableFiltersOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.nullablefiltersorplaceholders/index.md) | No | Specify filters to apply on the data to chart. | [`IWaterfallChartBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md) |
| [`height`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropsheight) | `number` | No | Set height of the chart (in pixels). | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropsloadingcomponent) | `ComponentType<`[`ILoadingProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iloadingprops/index.md)`>` | No | React component to display while loading data from the backend. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`locale`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropslocale) | `string` | No | Set Locale for visualization localization. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`onDataView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksondataview) | [`OnDataView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ondataview/index.md) | No | _(Alpha)_ Called when the visualization loads a DataView, i.e. it receives data from the backend. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onDrill`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksondrill) | [`OnFiredDrillEvent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onfireddrillevent/index.md) | No | Called when user triggers a drill on a visualization. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksonerror) | [`OnError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onerror/index.md) | No | Called when an error occurs while loading data for the visualization. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onExportReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksonexportready) | [`OnExportReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onexportready/index.md) | No | Called when the visualization is ready to be exported. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onLegendReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ichartcallbacks/index.md#ichartcallbacksonlegendready) | [`OnLegendReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.onlegendready/index.md) | No | Called when legend is rendered. | [`IChartCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ichartcallbacks/index.md) |
| [`onLoadingChanged`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksonloadingchanged) | [`OnLoadingChanged`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onloadingchanged/index.md) | No | Called when loading status of the visualization changes - vis starts or stops loading | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`placeholdersResolutionContext`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md#iwaterfallchartbucketpropsplaceholdersresolutioncontext) | `any` | No | Resolution context for composed placeholders. | [`IWaterfallChartBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md) |
| [`sortBy`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md#iwaterfallchartbucketpropssortby) | [`SortsOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.sortsorplaceholders/index.md) | No | Specify how to sort the data to chart. | [`IWaterfallChartBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md) |
| [`viewBy`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md#iwaterfallchartbucketpropsviewby) | [`AttributeOrPlaceholder`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributeorplaceholder/index.md) | No | Specify viewBy attribute that will be used to create the column There will be a column for each value of the attribute. | [`IWaterfallChartBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iwaterfallchartbucketprops/index.md) |
| [`width`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropswidth) | `number` | No | Set width of the chart (in pixels). | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`workspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md#ibucketchartpropsworkspace) | `string` | No | Identifier of analytical workspace, from which the chart will obtain data to visualize. If you do not specify workspace identifier, then you MUST have WorkspaceProvider up in the component tree. | [`IBucketChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md) |