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

# Single metric

> One aggregated number as a quick-glance KPI tile.

A **single metric** widget displays exactly one aggregated value in a large font — the simplest possible KPI tile. Use it when a single number tells the story: total spend this month, conversions to date, or click-through rate for a campaign.

## When to use a single metric

* **One-number KPIs** — the metric everyone should know at a glance.
* **Compact dashboard tiles** — side-by-side comparisons across multiple single-metric widgets, each pinned to a different metric.
* **Executive rollups** — the simplest way to communicate a single top-level number.

For multi-metric summaries, use the [Overview widget](/widgets/widget-library/other-widgets/overview-widget). For target tracking, use the [Goal widget](/widgets/widget-library/other-widgets/goal-widget).

## Configure a single metric

### Mandatory fields

<Steps>
  <Step title="Pick a data source">
    In the **Data sources** section, select the data source to include.
  </Step>

  <Step title="Pick a metric">
    Pick the metric shown as the widget's value — for example, Spend, Impressions, or Conversions. Only one metric is displayed.
  </Step>
</Steps>

Widget changes save automatically when the settings panel closes. Persist changes to the dashboard by clicking **Save dashboard**.

### Optional fields

* **Widget filter** — narrow the data feeding the widget. See [Filters](/dashboards/filters-and-dates/filters).
* **Period** — override the dashboard's date range. See [Date ranges](/dashboards/filters-and-dates/date-ranges).

## Comparison mode

Single metric widgets **support comparison mode**. When the Compare toggle is on at the dashboard or widget level, the widget shows the current value alongside the comparison-period value, with a delta.

## Conditional formatting

Single metric widgets support conditional formatting on the metric value's **text color**.

To set a rule:

1. Click the waterdrop icon next to the metric value in the widget settings.
2. Set a **Single color** rule with a condition and color.

For example: on a CPA single metric, apply Text color = red when CPA > \$50, so the value renders red only when it crosses the target.

<Note>
  Single metric supports **Single color** mode only — not Color scale.
</Note>

## Empty state

When the metric returns no value in the current date range, the widget renders a dash (`-`) in place of the value.

## Widget styling

Global widget style settings — font, border, background, and color themes — apply to every widget through the [Dashboard style settings](/dashboards/building/dashboard-style-settings#global-widget-settings). On top of those, Single metric widgets have style options unique to this widget type:

* **Metric value font** — weight, size (Auto or fixed), and HEX color for the aggregated value.
* **Number display** — controls how the value renders:
  * **Display format** — Short scale (compact notation like `12.3K`) or Full number (`12,345`).
  * **Decimal digits** — how many decimal places to show (for example, `0.0`).
* **Icon** — display an optional icon alongside the value. **Icon type** options:

  * **None** — no icon (default).
  * **Data source** — automatically uses the icon of the data source feeding the widget (for example, the Meta or Google Ads logo).
  * **Icon** — pick from a library of preset icons.

  When Icon type is anything other than None, the following properties can be customized: the icon choice from the library, **Position** (Left or Right of the value), **Size** (preset size list), and **Color** (HEX + opacity). Click **Reset** to clear icon properties back to defaults.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The widget shows a dash ('-')">
    The metric returned no value in the current date range. Widen the date range, remove restrictive widget filters, or pick a metric that has data in the current window. See [Data not loading](/troubleshooting/data-not-loading).
  </Accordion>

  <Accordion title="Value looks unexpectedly high or low">
    The metric is aggregated according to its own definition (sum, average, or ratio, depending on the metric). Confirm that the metric picked matches the aggregation expected — for example, "Total Spend" for a sum, "Average CPC" for an average.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Overview widget" href="/widgets/widget-library/other-widgets/overview-widget">
    Multiple single-metric tiles in one widget.
  </Card>

  <Card title="Goal widget" href="/widgets/widget-library/other-widgets/goal-widget">
    Track this metric against a target.
  </Card>
</CardGroup>