Pulse KPI interactive demo

Pulse KPI field guide

What each field in Pulse KPI's Build visual pane does, what to put in it, and the mistakes that are easy to make. Every line here describes what the visual's code does (src/visual.ts, src/model.ts and capabilities.json). You can try each one in the demo: run npm run demo, then open demo/index.html.

Value

What it means. The number the card shows, large. It's the only field the visual needs: until something is in Value, it shows a short note on what to add.

Column type. A number, or a measure. Power BI summarises a number column for you (Sum by default); pick Average in the field's menu for rates and percentages, which mean nothing added up. A blank or non-number result shows as a dash (—) on the card.

Good example. Revenue, as Sum of Revenue. Or a measure you wrote, such as Total revenue.

With a Date. The card shows the latest period that has a value, not the total. A period with a blank value is skipped, so the card falls back to the last period with data.

Tips

• With no Category, the card's name is the field's name as Power BI sends it, such as "Sum of Revenue". To show something better, use Rename for this visual on the field in the well, or a measure with a clear name.
• The value uses the column's own format string, so set the format on the column or measure in Power BI (currency, percentage, decimals).
• Display units set to Auto picks the unit from each card's own value, the way Power BI's own card does: no unit below 1,000, thousands from 1,000 to below one million ($88.30K, $391.84K), millions from one million ($1.15M), then billions and trillions. A value that rounds up to the next unit shows in it (999,999 is $1.00M). Cards side by side can still differ, such as $940.00K beside $1.15M; pick Thousands or Millions for cards that match.
• Decimal places apply only when the value is shown in a unit (thousands, millions and so on). Otherwise the column's format string decides the decimals.

Common mistakes

• Summing a rate. Ten regions at 3% don't make 30%. Use Average, or better, a measure that divides the totals.
• Storing a percentage as 0 to 100. The visual treats a value as a percentage when its format string contains %, and then reads changes in points (▲ 0.6 pt), multiplying the difference by 100. So store percentages as 0 to 1 (0.026) and format them as a percentage (2.6%). Stored as 2.6 with no % format, the card shows no % sign, and the changes read as a percentage of each other (▲ 12%) rather than in points. Stored as 2.6 with a % format, Power BI shows 260%.

Target

What it means. The goal the value is compared with. It gives the card its status (on track, at risk or off track), the "vs target" change, and the dashed target line on the trend, with its label ("Target $1.10M").

Column type. A number, summarised the same way as Value: Sum of Revenue target against Sum of Revenue, Average of Return rate target against Average of Return rate.

Good example. Revenue target, one row per month and region, as Sum.

If it's empty. The card shows its value, the change since the previous period and the trend, with no status and no target line.

How the status is worked out. The At risk within (% of target) option (10 by default, 0 to 100) sets a band beside the target, as a share of the target's size.

• Higher is better (the default): at or above the target is on track; below it but within the band is at risk; further below is off track.
• Lower is better, for costs, spend, return rates, waiting times or defects: at or below the target is on track; above it but within the band is at risk; further above is off track.

For example, with a target of 2.5% and the band at 10, the band is 0.25 points: 2.7% is at risk and 2.8% is off track. With the band at 20, 2.8% is at risk.

Tips

• With a Date, the card uses the target of the same period as the value it shows. If that period has no target, the card has no status, even when earlier periods had one.
• The "vs target" change is the difference as a percentage of the target, rounded to one decimal place (▲ 4.5%), or in points for a percentage. Its colour says whether it's good, by the direction you chose: a rise is good when higher is better, and bad when lower is better.
• The target's label on the trend uses the Value's format and display units, so give Target the same format as Value.

Common mistakes

• Leaving Better when the value is on Higher is better for a cost. Spend under budget then shows as off track. Set it to Lower is better (Format visual > Status).
• A target summed over the wrong rows. If the target is stored once per region but your rows are per day, Sum adds it up once per day. Use a target table at the same level as the value, or a measure.

Date

What it means. The periods for the trend line and for "since the previous period". Each card shows the latest period that has a value and compares it with the period before it that has a value ("vs Sep 2026 ▲ 10.4%").

Column type. A date column. The visual takes up to 1,000 periods.

Good example. Month, the first day of each month, used as the column itself.

If it's empty. Each card is the total for everything the report's filters allow, with no trend and no "vs previous" change. That's what you want for a total such as spend against budget.

Month or the date hierarchy. When Power BI's auto date/time is on, a date field comes with a Date Hierarchy (Year, Quarter, Month, Day). Microsoft's auto date/time article explains that you can switch a date field in a well between the column and the hierarchy from the field's menu. Pulse KPI has no drill-down, and its Date well takes one field, so pick the column itself (Month, not Date Hierarchy): you get one period per date in the column. If you use only the Year level, each period is a whole year, and the card compares the latest year with the one before.

Tips

• The period labels use the date column's format string; with none, they read like "Oct 2026". Set the column's format in Power BI to change them.
• The trend needs at least two periods, and room on the card: it's the first thing left out when a card is small.
• The two changes ("vs target" and "vs" the previous period) share one line where they fit. On a narrow card the second one wraps onto a line of its own, and on a very narrow card a change's words wrap inside it. Where a short card needs the room, its row grows to fit and the visual scrolls, so neither change is cut off. Screen readers and the tooltip give both, as before.
• A period with no value breaks the line; the trend picks up again at the next period with data.
• The latest period counts even when it's only partly over. If this month has three days of data, the card shows those three days against the whole month's target. Filter to complete periods if that's not what you want.

Common mistakes

• A completion date, due date or start date as Date. Each card then shows only the latest date that has a value: the last project to finish, not all of them. Leave Date empty for a total, or use a column that gives every row its reporting period (such as a report month).
• The Year level of the hierarchy. The card compares this year so far with all of last year. In the demo's sample, which starts in November 2025, each region shows as 440% to 500% up on 2025.
• A text column of month names. The card treats the last period it receives as the latest, so the periods have to arrive in date order. Use a real date column.

Category

What it means. Splits the visual into one card per item, such as one per region or per team, on a grid. Each card has its own latest period, target, status and trend.

Column type. Text, such as a name or a code.

Good example. Region (East, North, West), or Team.

If it's empty. One card shows everything in Value together.

Tips

• Up to 24 cards: the visual asks Power BI for the top 24 items and shows no more. To choose which 24, add a Top N filter to the visual in Power BI.
• An item with no name shows as "(Blank)".
• The cards go in a grid: as many columns as fit at Minimum card width (220 px by default, Format visual > Cards), and the rows share the visual's height. Below 128 px a row, the visual scrolls.
• With a Category, people can select a card (click it, or Tab to it and press Enter or Space; hold Ctrl for more than one) to filter the rest of the report page, where Power BI allows it. Without a Category there's nothing to filter by, so cards can't be selected.

Common mistakes

• A column with hundreds of items, such as customer names. Only 24 cards show, and they're too small to read. Use a higher-level column, or a Top N filter.
• A number or date column in Category. Use Value for numbers and Date for dates.

Tooltips

What it means. Up to five more measures that show in the card's tooltip when you hover over it, after the card's own figures.

Column type. Numbers, each summarised its own way and formatted with its own format string.

Good example. Average of Return rate beside a revenue card.

What the tooltip shows. The latest period and its value, the target, the change to the target, the previous period's value and the change since it, the status (when Show status is on), then each Tooltips field. A Tooltips field shows its latest value that isn't blank, and a field with no value at all is left out.

Tips

• Tooltips also work where Power BI turns selection off (on some dashboard tiles, for example), as Microsoft asks of visuals.
• The tooltip opens on hover. Someone using a keyboard or a screen reader hears each card's name, value, status and changes instead, so put anything essential on the card, not only in the tooltip.

The format options

These are in Format visual, and the demo's Format visual tab shows the same ones.

Dark reports. Pulse KPI draws its own cards, so on a dark report page set Cards > Background to a dark colour. The visual then uses light text and lighter status colours by itself.

High contrast. When Windows high contrast is on, the visual uses only the two colours Power BI gives it, with outlines instead of fills, and ignores the colours above.

The landing page. Before anything is in Value, the visual shows a short note on what to add, in the report theme's text colour on its background colour, so it reads on a light or a dark theme. In high contrast it uses the high contrast colours.

Quick fixes