> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/metric.md).

# Metric

The Avonni Metric component displays a key performance indicator or numerical value with optional label, description, avatar, and a secondary metric — making it ideal for dashboards and KPI summaries.

## Overview

Use the Metric component whenever you need to surface a single number prominently: total revenue, open case count, conversion rate, or any aggregate calculated directly from your Salesforce data. A secondary metric can sit beside or around the main value to add context (for example, a comparison to last period).

When connecting to the Query data source, write a query targeting a specific Salesforce object and field, then apply an aggregate function (sum, average, count, etc.) to calculate the displayed value directly from your records.

{% @arcade/embed url="<https://app.arcade.software/share/bN4fRigPBuqjBV09DpeI>" flowId="bN4fRigPBuqjBV09DpeI" %}

{% hint style="info" %}
**See it in a real project**

[Account Highlight Panel](https://docs.avonnicomponents.com/projects/use-cases/record-pages/account-highlight-panel): A custom highlights panel with metrics, badges and a gauge.
{% endhint %}

## Configuration

To configure the Metric, select it on the canvas. The **Edit Metric** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab from top to bottom.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FG25U37Te1cMQ8WiFA3AB%2Fmetric-builder-properties.png?alt=media" alt="The Properties tab of the Edit Metric panel" width="320"><figcaption><p>The Properties tab. The first group of fields carries no heading in the panel; <strong>Avatar</strong>, <strong>Primary Metric</strong> and <strong>Secondary Metric</strong> are collapsible sections below it.</p></figcaption></figure>

### Value and Label

The top of the Properties tab controls the metric's text content and layout. It is the one group with no heading of its own in the panel.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FI9xiieFDs3LKPmMHPKQH%2Fmetric-anatomy.png?alt=media" alt="A metric showing its label, description, value, secondary value and avatar"><figcaption><p>Every part of the component: the avatar, the <strong>Label</strong> above the <strong>Value</strong>, the <strong>Secondary Value</strong> beside it, and the <strong>Description</strong> underneath.</p></figcaption></figure>

* **Label** — Text displayed above (or below) the main value to name the metric being shown. Use the **Label Position** setting to place it at the top (default) or bottom.
* **Description** — Additional text shown below the label to provide context, units, or a time range.
* **Value** — The primary number to display. You can enter a static value or connect it to a Salesforce field. Requires **Format Style** to be set to a numeric mode (Decimal, Percent, Percent Fixed, or Currency). For a date value, set **Format Style** to Date instead — this switches the input to the **Value** date picker.
* **Secondary Value** — A supporting number rendered near the main value. Configure its position, format, and trend options in the **Secondary Metric** section below.
* **Label Position** — Controls where the label appears relative to the metric value: **Top** (default) or **Bottom**.

### Avatar

Add an avatar to give the metric visual identity — for example, an icon representing the metric category or a record image.

* **Variant** — Shape of the avatar: **Circle** or **Square** (default).
* **Initials** — Text initials shown inside the avatar when no image is set.
* **Icon Name** — Fallback icon displayed when the image fails to load.
* **Icon Size** — Size of the avatar: X-Small, Small, **Medium** (default), Large, X Large, or Xx Large.
* **Image** — URL or Content Document ID of the avatar image.
* **Alternative Text** — Accessible description of the avatar image.
* **Position** — Where the avatar is placed relative to the metric value: **Left** (default), Right, Bottom, or Top.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FsvP2kuJFZO6420XHA60q%2Fmetric-avatar-position.png?alt=media" alt="The four avatar Position values"><figcaption><p>The four values of the avatar <strong>Position</strong>.</p></figcaption></figure>

### Primary Metric

These settings control formatting and decoration of the main value. Which of them appear depends on **Format Style**, so they are grouped by the format they belong to.

#### Format Style

How the value is formatted: **Decimal** (default), Percent, Percent Fixed, Currency, or Date. Choosing Date switches the value input to a date picker and replaces the number settings with the date ones.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FxJN4D5dIVnLTH8zs3oCv%2Fmetric-format-style.png?alt=media" alt="The five Format Style values rendered from the same kind of value"><figcaption><p>The five values of <strong>Format Style</strong>. Percent multiplies the value by 100, so <code>0.62</code> reads as 62%, while Percent Fixed takes the number as written, so <code>62</code> also reads as 62%.</p></figcaption></figure>

#### Text around the value

| Setting     | Description                                                           |
| ----------- | --------------------------------------------------------------------- |
| **Prefix**  | Text shown immediately before the value (for example, `~` or `>`).    |
| **Suffix**  | Text shown immediately after the value (for example, `pts` or `hrs`). |
| **Tooltip** | Text displayed when a user hovers over the value.                     |

#### Number formatting

All of these require **Format Style** to be Decimal, Currency, Percent, or Percent Fixed.

| Setting                                                         | Description                                                                                                                                     |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Value Sign**                                                  | Which sign is shown in front of the value: **Negative** (default, shows `−` for negative numbers) or Positive (shows `+` for positive numbers). |
| **Maximum Fraction Digits** / **Minimum Fraction Digits**       | Bounds on the number of decimal places displayed.                                                                                               |
| **Maximum Significant Digits** / **Minimum Significant Digits** | Bounds on the total significant digits displayed.                                                                                               |
| **Minimum Integer Digits**                                      | Minimum digits before the decimal point (zero-padded).                                                                                          |

#### Currency

Both require **Format Style** = Currency.

| Setting                 | Description                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Currency Code**       | ISO 4217 code (e.g., `USD`) that determines which currency is displayed.                                     |
| **Currency Display As** | How the currency identifier is shown: **Symbol** (default), Code (e.g., `USD`), or Name (e.g., `US Dollar`). |

#### Trend

| Setting                    | Description                                                                                                                                                                                                          |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show Trend Color**       | When enabled, the value's color changes based on whether it is above or below the breakpoint (green for positive trend, red for negative). Requires **Format Style** = Decimal, Currency, Percent, or Percent Fixed. |
| **Trend Breakpoint Value** | The threshold number considered neutral. Values above it are treated as a positive trend; values below as negative. Requires **Show Trend Color** enabled.                                                           |
| **Trend Icon**             | An icon rendered alongside the value to signal direction: **Dynamic** (arrow direction flips automatically), **Arrow**, or **Caret**. Requires **Show Trend Color** enabled.                                         |

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FyrS0gJzfy6IZvJLcuXxm%2Fmetric-trend.png?alt=media" alt="Trend colour off, then the three Trend Icon values"><figcaption><p>Trend colouring off, then the three values of <strong>Trend Icon</strong>. The last metric sits below the breakpoint, so it turns red and the caret points down.</p></figcaption></figure>

#### Date formatting

All of these require **Format Style** = Date.

| Setting           | Description                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------ |
| **Day**           | Day format: 2-Digit or Numeric.                                                            |
| **Month**         | Month format: 2-Digit, Narrow, Short, or Long.                                             |
| **Year**          | Year format: 2-Digit or Numeric.                                                           |
| **Weekday**       | Weekday display: Narrow, Short, or Long.                                                   |
| **Era**           | Era display: Narrow, Short, or Long.                                                       |
| **Hour**          | Hour format: 2-Digit or Numeric.                                                           |
| **Minute**        | Minute format: 2-Digit or Numeric.                                                         |
| **Second**        | Second format: 2-Digit or Numeric.                                                         |
| **Hour 12**       | When enabled, time displays in 12-hour format; otherwise 24-hour.                          |
| **Timezone**      | IANA time zone (e.g., `America/New_York`). Defaults to the browser's time zone when empty. |
| **Timezone Name** | How the time zone label is shown: Short or Long.                                           |

### Secondary Metric

A secondary value that provides comparison or context for the main metric, for example a change against the previous period.

**The Secondary Metric section offers the same settings as Primary Metric**, applied to the secondary value: Format Style, the text, number, currency, trend and date settings all behave as described above. The only difference is that each one is gated on **Secondary Format Style** rather than on Format Style.

These three have no equivalent in the primary section:

| Setting      | Description                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| **Prefix**   | Text shown before the secondary value.                                                                   |
| **Suffix**   | Text shown after the secondary value.                                                                    |
| **Position** | Where the secondary value appears relative to the main value: Bottom, Left, **Right** (default), or Top. |

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FTGLODlmNou2k1MxwSwXy%2Fmetric-secondary-position.png?alt=media" alt="The four Secondary Metric Position values"><figcaption><p>The four values of the secondary <strong>Position</strong>.</p></figcaption></figure>

{% hint style="warning" %}
**Trend Breakpoint Value in this section follows the primary toggle.** The secondary **Trend Breakpoint Value** field only appears when the primary **Show Trend Color** is enabled, not the secondary one. Switch on Show Trend Color in **Primary Metric** to reach it.
{% endhint %}

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Metric. Configure them from the **Interactions** tab of the Edit Metric panel.

### Primary Metric Click

Fires when a user clicks the primary metric. Use this to navigate to a detail page, open a flow, or drive any logic tied to the primary value.

### Secondary Metric Click

Fires when a user clicks the secondary metric. Use this to trigger a separate action for the secondary value.

## Styling

The **Style** tab gives you fine-grained control over the Metric's appearance. Configure it from the **Style** tab of the Edit Metric panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the metric, creating space between it and other elements.

* **Top / Right / Bottom / Left:** Adjust the space on each side of the metric.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing between the metric's content and its border.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Size" %}
Controls the metric's dimensions.

* **Width / Height:** Set fixed dimensions.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
* **Overflow:** Control how content that exceeds the bounds is handled.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the metric.

* **Color:** Set the border color.
* **Size:** Adjust the border thickness.
* **Style:** Choose a border style (e.g. solid, dashed, dotted).
* **Radius:** Control the roundness of the corners.
  {% endtab %}

{% tab title="Alignment" %}
Aligns the metric content within the component.

* **Alignment:** Align the primary value, label, and description.
* **Secondary Alignment:** Align the secondary value block.
  {% endtab %}

{% tab title="Background" %}
Sets the metric's background.

* **Color:** Set the background color or apply a gradient.
  {% endtab %}

{% tab title="Label" %}
Styles the label text.

* **Color:** Set the label text color.
* **Font Size / Font Style / Font Weight:** Control the label typography.
* **Line Clamp:** Limit the label to a maximum number of lines.
  {% endtab %}

{% tab title="Description" %}
Styles the description text.

* **Color:** Set the description text color.
* **Font Size / Font Style / Font Weight:** Control the description typography.
* **Line Clamp:** Limit the description to a maximum number of lines.
  {% endtab %}

{% tab title="Value" %}
Styles the primary value.

* **Color:** Set the value text color.
* **Font Size / Font Style / Font Weight:** Control the value typography.
* **Line Height:** Adjust the line height of the value.
  {% endtab %}

{% tab title="Prefix" %}
Styles the text shown before the primary value.

* **Color:** Set the prefix text color.
* **Font Size / Font Style / Font Weight:** Control the prefix typography.
  {% endtab %}

{% tab title="Suffix" %}
Styles the text shown after the primary value.

* **Color:** Set the suffix text color.
* **Font Size / Font Style / Font Weight:** Control the suffix typography.
  {% endtab %}

{% tab title="Secondary" %}
Styles the secondary value and its parts.

* **Value:** Color; Font Size / Font Style / Font Weight.
* **Prefix:** Color; Font Size / Font Style / Font Weight.
* **Suffix:** Color; Font Size / Font Style / Font Weight.
* **Trend:** Background Color / Color / Radius (set per direction: Negative, Neutral, Positive).
  {% endtab %}

{% tab title="Trend" %}
Sets the colors used to represent the primary value's trend.

* **Negative Color / Neutral Color / Positive Color:** Set the trend text color for each direction.
  {% endtab %}

{% tab title="Avatar" %}
Styles the metric's avatar.

* **Icon Background Color / Icon Foreground Color:** Set the fallback icon colors.
* **Border Color / Border Size / Border Style / Border Radius:** Customize the avatar border.
* **Initials Color / Initials Color Hover / Initials Font Weight:** Style the avatar initials.
* **Vertical Alignment:** Align the avatar relative to the metric content.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Metric exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Interaction State

These variables reflect which metric the user last clicked.

| Output variable              | Type    | What it returns                                                                                          |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| **Primary Metric Clicked**   | Boolean | `true` when the user clicks the primary metric; use it to drive a visibility rule or conditional action. |
| **Secondary Metric Clicked** | Boolean | `true` when the user clicks the secondary metric.                                                        |

> **Example:** Use **Primary Metric Clicked** in a visibility rule to reveal a detail panel only after the user clicks the headline figure.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/metric.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.