# SmartVisuals Waterfall & PVM Bridge for Power BI

> Waterfall and PVM bridge for Power BI: free subtotals, variance bridges and IBCS. Premium splits the change into volume, mix, price, currency, new and lost.

- Page: https://www.smartvisuals.io/visuals/waterfall
- Fields and settings: https://www.smartvisuals.io/visuals/waterfall/settings
- Microsoft Marketplace: https://marketplace.microsoft.com/en-us/product/smartvisuals.smartvisuals-waterfall?tab=overview
- Package: https://www.smartvisuals.io/downloads/smartvisuals-waterfall-1.0.1.0.pbiviz
- Sample report (zipped .pbip): https://www.smartvisuals.io/samples/smartvisuals-waterfall-sample-1.0.1.0.zip
- Price: Free tier for every viewer; premium $2.99 per user per month or $29 per user per year on Microsoft Marketplace, with a 30-day free trial. Premium works in edit mode without a licence; unlicensed viewers see the free tier, never a blocked visual.
- Certified by Microsoft: yes
- Version: 1.0.1.0
- GUID (visualType and publicCustomVisuals): `waterfallPvmBridge7D3C9E21A4B84F6FA1E2C5D8B9F04A13`

## What is free

- **Waterfall with subtotals**: Thousands of steps, with subtotals and totals from a Step type field or an "=" name prefix, and invert per step.
- **Variance bridges**: Budget to actual or prior year to actual by category, from a comparison measure or a Period field.
- **Layout and order**: Vertical or horizontal, Top N with Others, sort by impact and drill-down.
- **IBCS and cost bridges**: IBCS notation (PY, PL, FC, AC) with hatched adverse bars, and lower is better for cost bridges.
- **Labels that add up**: Automatic axis break, difference highlight in value and %, a data table and labels that still add up after rounding.
- **Four themes, every option**: A one-line insight, four themes with their own personality, step colours per category with Power BI conditional formatting (fx), and every colour, font and label adjustable.
- **Native Power BI behaviour**: Cross-filtering, tooltips and report-page tooltips, keyboard navigation, high contrast and 20 languages.

## What premium adds

- **Price-volume-mix bridge**: Volume, mix and price from units and revenue, plus cost for a margin bridge, currency from constant-rate revenue, and new and lost items.
- **Four documented methods**: Price at current volume, price at base volume, a separate price-by-volume interaction or the symmetric midpoint, with mix and new/lost switches.
- **Chained multi-period bridges**: 2024 to 2025 to 2026 from one Period field, up to the latest 24 periods, for variance and price-volume-mix bridges.
- **Effects down to the item**: Break any effect down by product, see the top contributors in every tooltip, and an item table that ties the bars back to the items.
- **Small multiples**: One bridge per region or segment, on a shared or an independent scale.

## Fields

| Field | Internal name | Takes | Needed | What it is for |
| --- | --- | --- | --- | --- |
| Category | `category` | Column | Optional, up to 4 | Steps of the waterfall, or the items of a price-volume-mix bridge (product, customer, SKU). Add a hierarchy to drill. |
| Period | `period` | Column | Optional | Optional year, quarter or scenario field with two or more values: the first is the base, the last the current period. |
| Small multiples | `group` | Column | Optional | Optional field: one bridge per value, on a shared scale. |
| Value | `value` | Measure | Optional | The amount to bridge: revenue, sales, margin, cost. |
| Comparison value | `baseValue` | Measure | Optional | Budget, prior year or forecast for the same amount. Draws the start pillar and the change per category. |
| Volume | `volume` | Measure | Optional | Units sold (quantity). With a comparison, turns the bridge into price, volume and mix effects. |
| Comparison volume | `baseVolume` | Measure | Optional | Units in the comparison period or plan (not needed with a Period field). |
| Value at comparison FX | `valueFx` | Measure | Optional | Current value translated at the comparison period's exchange rates (constant currency). Adds a currency effect. |
| Cost | `cost` | Measure | Optional | Cost of the units sold. Turns the bridge into a margin bridge with a separate cost effect. |
| Comparison cost | `baseCost` | Measure | Optional | Cost in the comparison period (not needed with a Period field). |
| Step type | `stepType` | Measure | Optional | Optional per-row type for classic waterfalls: start, delta, subtract, subtotal or total (or 2, 0, -1, 1, 3). Use First or Max on a text column. |
| Tooltips | `tooltips` | Measure | Optional, up to 5 | Extra measures shown in the tooltip. |

## Format pane

Each card is a key under `visual.objects` in a PBIR visual.json; each setting is a property of it. Toggles take `true`/`false`, choices and text a value in single quotes (`'auto'`), numbers a `D` suffix (`12D`).

### Theme (`theme`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Theme | `selectedTheme` | `smartvisuals` (SmartVisuals), `dark` (Dark), `clean` (Clean (White)), `slate` (Slate) |
| Use report theme colors | `useReportTheme` | On / off |
| Font | `fontFamily` | `inter` (Inter), `segoe` (Segoe UI), `arial` (Arial), `georgia` (Georgia) |
| Transparent background | `transparentBg` | On / off |
| Background | `bgColor` | Colour |

### Chart type & method (`chart`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Chart type | `chartType` | `auto` (Automatic), `classic` (Waterfall), `variance` (Variance bridge), `pvm` (Price-volume-mix bridge) |
| Compare | `compare` | `lastTwo` (Last two periods), `firstLast` (First to last period), `chain` (Every period (chained)) |
| PVM method | `priceBasis` | `current` (Price at current volume), `base` (Price at base volume), `interaction` (Price at base volume, separate interaction), `midpoint` (Midpoint (symmetric)) |
| Separate mix effect | `separateMix` | On / off |
| New and lost items as effects | `separateNewLost` | On / off |
| Hide zero effects | `hideZero` | On / off |
| Break down effect by item | `breakdown` | `none` (None), `volume` (Volume), `mix` (Mix), `price` (Price), `cost` (Cost), `interaction` (Price × volume), `fx` (Currency), `new` (New items), `lost` (Lost items), `other` (Other) |
| Items per broken-down effect | `breakdownN` | Number |
| Value at comparison FX holds | `fxMode` | `prior` (Current period at the previous period's rates), `constant` (Every period at constant rates) |
| Notation | `notation` | `standard` (Standard), `ibcs` (IBCS) |
| Comparison scenario | `scenario` | `PY` (Prior year (PY)), `PL` (Plan (PL)), `FC` (Forecast (FC)) |

### Layout (`layout`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Orientation | `orientation` | `vertical` (Vertical), `horizontal` (Horizontal) |
| Sort steps | `sortBy` | `data` (Data order), `impact` (Largest impact first), `valueDesc` (Value, high to low), `valueAsc` (Value, low to high), `name` (Name, A to Z) |
| Show top N steps (0 = all) | `topN` | Number |
| Bar width % (0 = theme) | `barWidth` | Number |
| Others label (blank = Others (n)) | `othersLabel` | Text |

### Legend (`legend`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Legend | `show` | On / off |
| Position | `position` | `top` (Top), `bottom` (Bottom) |
| Font size | `fontSize` | Number |
| Font color | `fontColor` | Colour |

### Effect names (`effectNames`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Volume | `volume` | Text |
| Mix | `mix` | Text |
| Price | `price` | Text |
| Cost | `cost` | Text |
| Price × volume | `interaction` | Text |
| Currency | `fx` | Text |
| New items | `new` | Text |
| Lost items | `lost` | Text |
| Other | `other` | Text |

### Bars & colors (`colors`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Color bars | `colorMode` | `direction` (Increase / decrease), `effect` (By effect or category) |
| Direction | `polarity` | `higher` (Higher is better), `lower` (Lower is better) |
| Increase | `increaseColor` | Colour |
| Decrease | `decreaseColor` | Colour |
| Start pillar | `startColor` | Colour |
| End pillar | `totalColor` | Colour |
| Subtotals | `subtotalColor` | Colour |
| Hatch adverse bars | `hatchAdverse` | On / off |

### Step colors (`dataPoint`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Color | `fill` | Colour |

### Effect colors (`effectColors`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Volume | `volume` | Colour |
| Mix | `mix` | Colour |
| Price | `price` | Colour |
| Cost | `cost` | Colour |
| Price × volume | `interaction` | Colour |
| Currency | `fx` | Colour |
| New items | `new` | Colour |
| Lost items | `lost` | Colour |
| Other | `other` | Colour |

### Connectors (`connectors`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Connector lines | `show` | On / off |
| Color | `color` | Colour |
| Style | `style` | `theme` (Theme), `solid` (Solid), `dashed` (Dashed), `dotted` (Dotted) |
| Width (0 = theme) | `width` | Number |

### Data labels (`labels`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Data labels | `show` | On / off |
| Show | `content` | `value` (Value), `pct` (% of start), `both` (Value and %) |
| Display units | `displayUnits` | `auto` (Auto), `none` (None), `K` (Thousands), `M` (Millions), `B` (Billions) |
| Decimal places | `decimals` | `auto` (Auto), `0`, `1`, `2`, `3` |
| Position | `position` | `outside` (Outside end), `inside` (Inside end) |
| Rounded labels add up | `reconcile` | On / off |
| Font size | `fontSize` | Number |
| Font color | `fontColor` | Colour |
| % of start color | `pctColor` | Colour |

### Category labels (`categoryAxis`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Category labels | `show` | On / off |
| Font size | `fontSize` | Number |
| Font color | `fontColor` | Colour |
| Effect and period bands | `bandColor` | Colour |

### Start & end pillars (`pillars`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Start pillar | `showStart` | On / off |
| Start label (blank = field name) | `startLabel` | Text |
| End pillar / total | `showEnd` | On / off |
| End label (blank = field name) | `endLabel` | Text |

### Value axis (`valueAxis`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Axis labels | `show` | On / off |
| Gridlines | `showGrid` | On / off |
| Grid color | `gridColor` | Colour |
| Font size | `fontSize` | Number |
| Font color | `fontColor` | Colour |
| Baseline color | `lineColor` | Colour |
| Axis break for small steps | `axisBreak` | On / off |

### Difference highlight (`difference`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Difference highlight | `show` | On / off |
| Show | `mode` | `both` (Value and %), `abs` (Value), `pct` (%) |
| Color | `color` | Colour |
| Font size | `fontSize` | Number |

### Data table (`table`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Data table | `show` | On / off |
| Font size | `fontSize` | Number |
| Font color | `fontColor` | Colour |
| Header color | `headerColor` | Colour |
| Rule lines | `ruleColor` | Colour |
| Item table (effects per item) | `itemTable` | On / off |
| Items in the item table | `itemRows` | Number |

### Small multiples (`smallMultiples`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Columns (0 = auto) | `columns` | Number |
| Shared scale | `sharedScale` | On / off |
| Panel titles | `showTitles` | On / off |
| Title font size | `titleFontSize` | Number |
| Title color | `titleColor` | Colour |

### Insight & footnote (`insights`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Insight sentence | `showInsight` | On / off |
| Insight font size | `insightFontSize` | Number |
| Insight color | `insightColor` | Colour |
| Method footnote | `showFootnote` | On / off |
| Footnote font size | `footnoteFontSize` | Number |
| Footnote color | `footnoteColor` | Colour |

### Accessibility (`accessibility`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Focus outline color | `focusColor` | Colour |
| Focus outline width | `focusWidth` | Number |
| Minimum text size | `minFontSize` | Number |
| Hatch adverse bars | `hatchAdverse` | On / off |