The KPI widget surfaces a single headline metric — a number, percentage, trend, or comparison — pulled directly from a query result. It is designed to be read at a glance.
Reading the data
The KPI widget takes the first value from the first row of your query result. Write your query to return exactly one meaningful value:
-- Good — returns a single scalar
SELECT COUNT(*) AS total_signups FROM users WHERE created_at >= NOW() - INTERVAL '30 days'
-- Good — returns one row, KPI reads the first column
SELECT SUM(revenue) AS mrr FROM subscriptions WHERE status = 'active'
—. An empty result set (zero rows) also displays as —, not 0.
KPI types
The KPI type controls how the query result is interpreted and displayed.
| Type | Description |
|---|
| Number | Displays a single numeric value |
| Percentage | Displays the value as a percentage — typically used when your query already returns a 0–100 (or 0–1) value |
| Trend | Shows the current value alongside a change indicator (up/down) against a previous period |
| Comparison | Shows two values side-by-side — the current value against a baseline |
Display options
Open the KPI widget settings to configure what is shown alongside the metric.
| Option | Description |
|---|
| Title | The label displayed above or below the metric value. Defaults to the widget name |
| Prefix | Text displayed immediately before the value (e.g. $, €, £) |
| Suffix | Text displayed immediately after the value (e.g. %, ms, users) |
| Icon | An emoji or image shown alongside the title for visual context |
Number formatting
Control how the raw numeric value is displayed.
| Setting | Description |
|---|
| Style | Number (default), Percent, Scientific, or Currency |
| Separator style | 100,000,000 (Western thousands separator) or 1,00,00,000 (Indian lakh separator) |
| Decimal places | Number of decimal digits to show (0–5) |
| Multiply by | Scale factor applied before display. Enter 0.001 to convert milliseconds to seconds, 100 to convert a 0–1 fraction to a percentage, etc. |
Multiply by and decimal places together — a common pattern is to set Multiply by to 0.001 and Decimal places to 1 to display a value stored in milliseconds as 1.2 s.
Compact notation
Compact notation abbreviates large numbers so they fit cleanly in the widget.
| Setting | Displays as |
|---|
| None | Full number — 1,234,567 |
| K | Thousands — 1.2K |
| M | Millions — 1.2M |
| B | Billions — 1.2B |
| Auto | Automatically selects K, M, or B based on the magnitude of the value |
Trend graph
Enable Show mini graph to display a small sparkline chart beneath the metric value. The sparkline is driven by the same query — it uses all rows returned, plotting each row as a point on the trend line.
For the sparkline to be meaningful, write a query that returns multiple rows (one per time period):
SELECT
DATE_TRUNC('day', created_at) AS day,
COUNT(*) AS signups
FROM users
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY 1
ORDER BY 1
If you enable the trend graph but your query returns only one row, the sparkline will appear as a flat line.
Directional signals
KPI signals show an up or down arrow next to the value to indicate direction. Useful for metrics where the viewer needs to know immediately whether the number is good or bad.
| Setting | Behaviour |
|---|
| None | No arrow shown |
| Positive | Green up arrow when value is positive, red down arrow when negative |
| Negative | Red up arrow when value is positive, green down arrow when negative (for cost or churn metrics where up is bad) |
| Both | Shows an arrow in the neutral accent color regardless of sign |
Icon
The Icon field accepts an emoji character. It appears alongside the KPI title and acts as a quick visual identifier when multiple KPI widgets appear on the same dashboard.
Examples: 💰 for revenue, 👥 for users, ⚡ for performance, 🛒 for orders.
The icon is decorative — it does not affect the value or any calculations. Last modified on March 11, 2026
Docs
Guides
