> 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" %}

## Configuration

To configure the Metric, select it on the canvas. The **Edit Metric** panel opens on the right. The sections below mirror the configuration panel from top to bottom.

### Content

The top section of the panel controls the metric's text content and layout.

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

### Primary Metric

These settings control formatting and decoration of the main value.

* **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.
* **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 reveals date-specific formatting fields.
* **Currency Code** — ISO 4217 code (e.g., `USD`) that determines which currency is displayed. Requires: **Format Style** = Currency.
* **Currency Display As** — How the currency identifier is shown: **Symbol** (default, e.g., `$`), Code (e.g., `USD`), or Name (e.g., `US Dollar`). Requires: **Format Style** = Currency.
* **Value Sign** — Controls which sign is shown in front of the value: **Negative** (default, shows `−` for negative numbers) or Positive (shows `+` for positive numbers). Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Maximum Fraction Digits** / **Minimum Fraction Digits** — Bounds on the number of decimal places displayed. Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Maximum Significant Digits** / **Minimum Significant Digits** — Bounds on the total significant digits displayed. Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Minimum Integer Digits** — Minimum digits before the decimal point (zero-padded). Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **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.

**Date formatting options** (all 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.

* **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.
* **Format Style** — Formatting for the secondary value: **Decimal** (default), Percent, Percent Fixed, Currency, or Date.
* **Currency Code** — ISO 4217 code for the secondary value. Requires: **Format Style** = Currency.
* **Currency Display As** — How the secondary currency identifier is shown: **Symbol** (default), Code, or Name. Requires: **Format Style** = Currency.
* **Value Sign** — Sign display for the secondary value: **Negative** (default) or Positive.
* **Maximum / Minimum Fraction Digits** — Decimal place bounds for the secondary value. Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Maximum / Minimum Significant Digits** — Significant digit bounds. Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Minimum Integer Digits** — Minimum integer digits for the secondary value. Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Show Trend Color** — Colorizes the secondary value based on trend direction. Requires: **Format Style** = Decimal, Currency, Percent, or Percent Fixed.
* **Trend Breakpoint Value** — Neutral threshold for secondary trend evaluation. Requires: **Show Trend Color** enabled.
* **Trend Icon** — Icon style for secondary trend direction: Dynamic, Arrow, or Caret. Requires: **Show Trend Color** enabled.

Secondary date formatting options mirror the primary metric date settings (Day, Month, Year, Weekday, Era, Hour, Minute, Second, Hour 12, Timezone, Timezone Name), and all require **Format Style** = Date.

### Set Component Visibility

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

## 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 Value" %}
Styles the secondary value.

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

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

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

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

* **Color:** Set the secondary suffix text color.
* **Font Size / Font Style / Font Weight:** Control the secondary suffix typography.
  {% 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="Secondary Trend" %}
Sets the colors and shape used to represent the secondary value's trend (set per direction: Negative, Neutral, Positive).

* **Background Color:** Set the trend background color.
* **Color:** Set the trend text color.
* **Radius:** Control the roundness of the trend badge corners.
  {% 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 %}


---

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