# Waterfall Chart (Beta)

The Waterfall widget lets you visualize cumulative changes across categories, making it easy to understand how individual areas contribute to an overall metric over a given period.

## Overview

The Waterfall chart breaks down a total metric into its component parts, showing positive and negative contributions from each category on the horizontal axis. It is particularly useful for tracking performance across regions, teams, or segments — for example, how each area contributed to an overall satisfaction score over the last 30 days.

## Configuring the Waterfall Widget

You configure the Waterfall widget through a three-tab panel: **General**, **Setup**, and **Filter**. Each tab controls a distinct aspect of the widget's behavior and display.

{% stepper %}
{% step %}
**Open the widget editor**

From your dashboard, add a new widget or click the edit icon on an existing one. The **Edit widget** panel opens on the right side of the screen.
{% endstep %}

{% step %}
**Select the Waterfall chart type**

In the **General** tab, locate the chart type selector. Click **Waterfall** to apply this visualization to the widget.
{% endstep %}

{% step %}
**Name the widget**

Still in the **General** tab, enter a descriptive name in the **Title** field. Optionally, add a **Subtitle** to provide additional context — this appears as smaller text beneath the title on the dashboard.

{% hint style="info" %}
The subtitle is hidden by default on the dashboard view. Use it to explain the metric being tracked or the scope of the data, so other users understand the widget's purpose at a glance.
{% endhint %}
{% endstep %}

{% step %}
**Configure the axes**

Switch to the **Setup** tab to define what data the chart displays.

**Vertical axis**

Under **Vertical axis**, use the **Metric** dropdown to select the measure you want to visualize (for example, *Overall*). Optionally, enable **Set vertical axis range** and enter custom **From** and **to** values to fix the Y-axis scale.

**Horizontal axis**

Under **Horizontal axis**, configure the following fields:

| Field             | Description                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Primary breakdown | The dimension used to segment the data on the X-axis (for example, *Areas*)                                            |
| Selection         | The specific values from the breakdown dimension to include. Click the dropdown to select or deselect individual items |
| Limit             | The maximum number of bars to display on the chart                                                                     |
| Start period      | The time range for the starting reference value (for example, *Last 30 days*)                                          |
| End period        | The time range for the ending reference value (for example, *Last 30 days*)                                            |

{% hint style="info" %}
The **Start period** and **End period** fields define the comparison window for calculating the waterfall values. When both are set to the same period, the chart shows contributions within that single range.
{% endhint %}
{% endstep %}

{% step %}
**Adjust display settings**

Still in the **Setup** tab, scroll to the **Display settings** section and toggle the options that apply:

| Setting                     | Description                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------- |
| Invert colors               | Reverses the default color scheme for positive and negative bars                      |
| Always show values on chart | Displays numeric labels directly on each bar, regardless of bar size                  |
| Show Mix Effect             | Adds a bar representing the blended or combined effect across the breakdown dimension |
| {% endstep %}               |                                                                                       |

{% step %}
**Apply filters**

Switch to the **Filter** tab to control which data the widget includes.

* Use the **date range dropdown** at the top to set the default time period for the widget. The default is *Last 30 days*.
* Under **Advanced filters**, click **+ Add filter** to add one or more property-based conditions that refine the data set.
* Enable **Ignore global filter** if you want this widget to display data independently, regardless of any filters applied at the dashboard level.

{% hint style="warning" %}
Enabling **Ignore global filter** means this widget will not respond to date range or segment filters applied to the rest of the dashboard. Use this setting intentionally when you need a fixed reference point that should always remain constant.
{% endhint %}
{% endstep %}

{% step %}
**Preview and save**

Click **Update preview** to verify the chart renders correctly with your configuration. Once satisfied, click **Save changes** to publish the widget to the dashboard.
{% endstep %}
{% endstepper %}

## Field Reference

### General Tab

| Field      | Description                                                           |
| ---------- | --------------------------------------------------------------------- |
| Chart type | The visualization type. Select **Waterfall** to use this chart format |
| Title      | The widget's display name, shown prominently on the dashboard         |
| Subtitle   | Optional description text shown beneath the title                     |

### Setup Tab — Vertical Axis

| Field                   | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| Metric                  | The measure to plot on the Y-axis                      |
| Set vertical axis range | Fixes the Y-axis to a custom minimum and maximum value |

### Setup Tab — Horizontal Axis

| Field             | Description                                           |
| ----------------- | ----------------------------------------------------- |
| Primary breakdown | The dimension used to split data into individual bars |
| Selection         | The subset of dimension values to display             |
| Limit             | Maximum number of bars shown                          |
| Start period      | Time window for the base value                        |
| End period        | Time window for the final value                       |

### Setup Tab — Display Settings

| Setting                     | Default | Description                             |
| --------------------------- | ------- | --------------------------------------- |
| Invert colors               | Off     | Swaps positive and negative bar colors  |
| Always show values on chart | On      | Displays data labels on every bar       |
| Show Mix Effect             | On      | Adds a combined-effect bar to the chart |

### Filter Tab

| Field                | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| Date range           | Default time period applied to the widget                   |
| Advanced filters     | Additional property filters to narrow the data              |
| Ignore global filter | Prevents dashboard-level filters from affecting this widget |

## Troubleshooting & FAQs

<details>

<summary>The preview is blank after configuring the axes. What should I check?</summary>

Verify that the **Selection** field under Horizontal axis has at least one value selected, and that the chosen **Start period** and **End period** contain data for the selected metric.

</details>

<details>

<summary>Why are some bars missing from the chart?</summary>

The **Limit** field caps the number of bars displayed. Increase this value in the Setup tab to show more breakdown categories.

</details>

<details>

<summary>The chart is showing unexpected values when the dashboard filter changes.</summary>

If the widget should remain unaffected by dashboard-level filtering, enable **Ignore global filter** in the Filter tab.

</details>

<details>

<summary>What does the Mix Effect bar represent?</summary>

The Mix Effect bar captures the portion of the total change that results from shifts in the composition of the breakdown dimension rather than performance changes within individual categories. Disable **Show Mix Effect** in Display settings if you do not need this breakdown.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ask.birdie.ai/voice-of-customer/dashboards-and-reporting/dashboard-widgets/waterfall-chart-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.