> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supaboard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# KPI Widget

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:

```sql theme={null}
-- 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'
```

If your query returns multiple rows, only the first row is used. If it returns multiple columns, only the first column is used as the primary metric — subsequent columns may be used by certain KPI types for comparison values.

**Null results** display as `—`. 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                   |

Prefix and suffix are visual only — they do not affect the underlying number or any calculations.

# 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 |

**Auto** is recommended for metrics whose value can vary across orders of magnitude (e.g. revenue that might be in the thousands one month and millions the next).

# 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):

```sql theme={null}
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
```

The KPI displays the **last row's value** as the headline number, and all rows as the sparkline.

> 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                                                   |

Choose **Negative** for metrics like error rate, churn, or cost — where a higher number is worse.

# 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.