KPI Cards

Overview

KPI (Key Performance Indicator) cards display important metrics in a clear, focused format. Use them to track single values, compare performance across time periods, or display multiple related metrics together.

Single Metric KPI

Create a single metric KPI by adding one metric without any groupBy fields. This displays a large, prominent value with an optional title and description.

How to create:

1. Add a metric (e.g., Sum of Sales)
2. Do not add any groupBy fields
3. Set a descriptive title

Period Comparison KPI

Period comparison KPIs show how a metric changes against a previous period, previous year, or fixed target. See Metric Comparisons for the complete mental model, precedence rules, and availability behavior.

To configure an explicit KPI comparison:

1. Add a metric to a KPI visual.
2. Give the KPI a date to compare over: a Trend By date shown on the card, a date field you set for it, or the dataset's primary date field.
3. Select a date range with a start and end, from Global Date or on the card.
4. Open the metric settings and choose Previous Period, Previous Year, Target, Off, or Inherit dashboard comparison.
5. For a period comparison, configure the offset, To date behavior, and calendar or weekday alignment.

For a single-value KPI, you don't need to add the date to Trend By when it already comes from the card or the dataset.

When the metric is set to Inherit dashboard comparison, a viewer can select Previous period or Previous year from the Global Date control. An explicit metric comparison or Off setting takes precedence over that viewer selection.

The card displays:

• The current value, as large as the card allows
• Under it, the change ("↗ +8.2%") and what it compares with ("vs $20.7M previous")
• On hover over the change, the resolved windows and configuration details

Comparison Configuration

The metric settings choose the baseline and favorable direction. The visual's Comparison section controls how the result is presented.

Calculation Type

Choose how the comparison is calculated:

Format Options

Difference inherits the metric's compatible number formatting by default. Percent change and ratio support 0–6 decimal places.

Indicator Settings

Customize the comparison badge:

• Indicator - Arrow + badge, Arrow, Badge, or None
• Color - Enable or disable sentiment color and customize increase, decrease, and no-change colors
• Favorable direction - Higher is better, Lower is better, or Neutral

Higher is better is the default. If a metric's favorable direction is set in your semantic model, that setting wins over the visual setting.

Labels

Conditional Labels - Display dynamic labels based on the comparison result:

• Increase - Shown when current > previous (default: "Increase")
• Decrease - Shown when current < previous (default: "Decrease")
• No Change - Shown when values are equal (default: "No change")

Comparison Label - Customize the comparison label (default: "Previous")

• Examples: "Last Month", "Last Year", "Last Period"

Below the Value

A KPI can show one more thing under its value and comparison:

• Trend: turn on the visual's Trend switch to draw a line of the metric over the period the KPI counts, such as each day of the last 7 days or each month of this year.
• With Trend off (the default), the card shows its drivers when its summary shows on the card; otherwise, for a target comparison, how far the value is toward the target; otherwise nothing.

When a card is too short for everything, a trend you turned on keeps its room: the date range under the title gives way first, then the description. The value and its comparison never give way to the trend.

The trend uses the date the KPI already counts on: its Trend By date, or the dataset's primary date, or the field of the dashboard's date filter. You don't need to add a Trend By. It runs one more query for the card.

The line covers the same dates as the value, so its points add up to it for a total. Under Grain, Automatic (the default) fits the line to that period:

Change the dashboard's date or click another chart, and Automatic follows. You can also pick one grain for the card. When the KPI has a Trend By, its grain sets the line's grain. When the period is one period of the grain, such as this month by month, the line shows the 12 periods ending with it, so the value is seen against its history. With no date range, the line shows the last 12 periods. A grain that would draw more than 400 points draws no line.

The first and last points can cover only part of their period: a week the date range starts in the middle of, or this month so far. The line into such a point is dashed, and its tooltip says so ("from Aug 6", "so far"). A period with no data is a gap in the line, not a zero. Hover over the line to see each period and its value. The editor's Date section shows what the line draws, for example "By week · 14 points".

Drivers list as many as fit. +N more opens every driver with the card's summary, and clicking a driver filters the dashboard to it.

Fitting the Card

A KPI reads the same at any size you give it. When the value doesn't fit, it shortens ($22.4M) and shows the full value on hover. As the card gets shorter, the date range under the title goes first, then the description, then the other metrics, then the comparison; the value always stays. What shows below the value needs room under it: a very short card leaves it out, and a wide, short card puts it beside the value.

Multi-Metric KPI (Up to 3 Metrics)

Display multiple related metrics in a single card when you need to show current performance alongside benchmarks or historical values.

How to create:

1. Add up to 3 metrics (e.g., Current Period, Previous Period, Budget)
2. Do not add any groupBy fields

Layout:

• Primary metric displays large at the top
• Secondary and tertiary metrics display side-by-side below in a 2-column grid
• Each metric shows its own label
• Card title typically describes the primary metric

The separate Enable metric comparison option on a two-metric KPI compares those two displayed metrics. It is not a period-over-period baseline. When several headline measures each need their own period comparison, use separate single-metric KPI cards so each result has an unambiguous value, baseline, and favorable direction.

Formatting

Number Formatting

• Decimal Places - Control precision (0-10 decimal places)
• Thousands Separator - Automatic based on locale
• Compact Notation - Display large numbers with K, M, B suffixes

Currency Formatting

• Currency Symbol - Select from major currencies (USD, EUR, GBP, etc.)
• Locale - Controls number formatting and symbol position
• Custom Symbol - Override default currency symbol if needed

When currency or locale is left unset, an eligible KPI can inherit the viewer's Display format preferences. An explicit KPI format remains more specific than the report default.

Percentage Display

• Multiply by 100 - Automatically convert decimals (0.25 → 25%)
• Decimal Precision - Control decimal places for percentages

Color Ranges

Apply conditional coloring based on value thresholds:

1. Define ranges (e.g., 0-50: Red, 50-75: Yellow, 75-100: Green)
2. Values automatically colored based on their range
3. Useful for status indicators and performance tracking

Best Practices

Single Metric KPIs:

• Use for the most important top-line metrics
• Keep titles clear and specific
• Add descriptions for context when needed

Period Comparison KPIs:

• Best for tracking trends over time
• Choose the baseline that matches your analysis period
• Customize "Previous" label to match your time period

Multi-Metric KPIs:

• Ideal for showing current value with context (previous, budget, target)
• Upto to 3 metrics for readability
• Use clear, concise labels for each metric
• Primary metric should be the most important value