> 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/flow/flow-components/metric.md).

# Metric

The Avonni Metric displays numerical values with labels to provide context for key metrics and performance indicators

## Overview

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-138c711c153df021544acc05c170e63c0187074f%2Fimage%20(52).avif?alt=media" alt="" width="375"><figcaption></figcaption></figure>

The Avonni Metric displays a key number (or date) with an optional label, description, avatar, prefix/suffix, and secondary value. Use it to surface KPIs, aggregated totals, or any single-value insight directly on a Flow screen.

***

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

## Set up a Metric

From an empty screen to a working metric. Every setting named here has its full reference further down the page.

{% stepper %}
{% step %}

#### **Add the Metric to your screen**

Open your screen in Flow Builder, search the components palette for **Avonni Metric**, and drag it onto the screen. Select it, then click **Open Component Builder**.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FUOescLCeYVVvpJ4ndmwN%2Fmetric-screen-editor.png?alt=media" alt="Flow Builder&#x27;s Edit Screen modal with the components palette filtered to Avonni Metric, and the component sitting on the screen canvas"><figcaption><p>The Metric comes from the components palette, the same place as every other Avonni screen component.</p></figcaption></figure>
{% endstep %}

{% step %}

#### **Start from a template**

The Metric ships with five ready-made configurations: **Currency**, **Currency with Secondary Value**, **Custom Style**, **Custom Suffix**, and **Percent**. Open the [Templates](/flow/component-builder/component-templates.md) panel from the button in the Component Builder's top-left corner, pick the one closest to what you need, and adjust it. Skip this step to configure from scratch.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2F8eJ8cbFmcmWaH8kWf6xz%2Fmetric-templates.png?alt=media" alt="The Templates panel of the Component Builder listing the five standard Metric templates, each with a live preview" width="320"><figcaption><p>Five starting points, each a working Metric you can edit. The <strong>Custom</strong> tab holds the templates you save yourself.</p></figcaption></figure>
{% endstep %}

{% step %}

#### **Choose how the value is formatted**

Under **Primary Metric**, set **Format Style** first: it decides what the rest of the group offers. **Decimal**, **Percent**, **Percent Fixed** and **Currency** give you a number, and **Currency** adds **Currency Code** and **Currency Display As**. **Date** gives you a date instead, and swaps the number settings for the date ones.
{% endstep %}

{% step %}

#### **Give it a value**

Set **Value**. It takes a number you type, a flow resource, or a query that aggregates records. Under **Format Style** **Date**, the same field takes a date.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FwGE4JGWWhy8QpwM9wStg%2Fmetric-properties.png?alt=media" alt="The Properties tab of the Metric property editor, showing the Primary Metric group with Format Style set to Currency" width="320"><figcaption><p>The <strong>Primary Metric</strong> group with <strong>Format Style</strong> set to <strong>Currency</strong>. <strong>Currency Code</strong> and <strong>Currency Display As</strong> are there because of that choice.</p></figcaption></figure>
{% endstep %}

{% step %}

#### **Label it**

Set **Label** above the value and **Description** below it, so the number reads as something. Both are optional, and a metric with neither is a number on a screen.
{% endstep %}

{% step %}

#### **Save and run the flow**

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fa4hYWyLmjvBTQVk5xSgD%2Fmetric-screen.png?alt=media" alt="A Metric on a flow screen: an avatar, the label Open Pipeline, a currency value, a green trend badge and a description underneath"><figcaption><p>The finished Metric on a flow screen, here with an avatar and a secondary value carrying a trend badge.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

## Tutorials

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Introduction 101 [VIDEO]</strong></td><td></td><td></td><td><a href="https://flow.avonnicomponents.com/tutorials/components/metric/introduction">https://flow.avonnicomponents.com/tutorials/components/metric/introduction</a></td><td><a href="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-b119b96d5dfebbaca585b679179af97cb81e0819%2Fmodern%20(26).png?alt=media">modern (26).png</a></td></tr><tr><td><strong>Building a Dynamic Map with reactive metrics</strong></td><td></td><td></td><td><a href="broken://spaces/dHOej9Pd5IxJNGEJMZKW/pages/ycDXF0y2Fj6NpL8x9es3">Broken link</a></td><td><a href="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-6745b69580f67f78343581d5abee5e92201b32a5%2Fimage%20(20).avif?alt=media">image (20).avif</a></td></tr><tr><td><strong>Build a Reactive Metrics Dashboard using the Avonni Metric and Data Table [VIDEO]</strong></td><td></td><td></td><td><a href="https://youtu.be/sRtkMi2Mmqg">https://youtu.be/sRtkMi2Mmqg</a></td><td><a href="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-779fec19f24dde51488443c4daf7fc79fca7b287%2Fmodern%20(25).png?alt=media">modern (25).png</a></td></tr><tr><td><strong>Build a user activity report</strong></td><td></td><td></td><td><a href="broken://spaces/dHOej9Pd5IxJNGEJMZKW/pages/nc2JHlE7juCFClmf9jyN">Broken link</a></td><td><a href="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-11c2d9b51228e5377cc7b6b181b04f422b473dd4%2FDesign%20sans%20titre%20(52).png?alt=media">Design sans titre (52).png</a></td></tr></tbody></table>

***

## Configuration

To configure it, click the component on the Flow screen. The Edit Metric Component panel opens on the right with three tabs: Properties, Interactions, and Style. The sections below mirror the Properties tab.

### Properties

* **Label** — text displayed above the metric value. When set, it appears above the data by default.
* **Description** — brief text displayed below the metric value to provide additional context.

### Avatar

Display an avatar near the metric value. Configure the avatar's image source, initials, fallback icon, variant, size, alternative text, and **Position** relative to the value: **Left** (default), **Right**, **Bottom**, or **Top**.

### Primary Metric

Configure the main number (or date) displayed prominently in the component.

* **Format Style** — determines whether the value is displayed as a number or a date, and how it is formatted:
  * **Decimal**: standard number formatting
  * **Percent**: multiplies the value by 100 and appends a `%` symbol, so `0.65` renders as `65%`
  * **Percent Fixed**: appends a `%` symbol without multiplying, so `65` renders as `65%`
  * **Currency**: formats as a currency amount. Configure **Currency Code** (for example USD) and **Currency Display As** (Symbol, Code, or Name)
  * **Date**: formats as a date. Use the date/time formatting options below
* **Value**: the number displayed. It is a single field that accepts a number you type, a flow resource, or a query that aggregates records with SUM, COUNT, AVG, MIN or MAX, in which case the aggregated result is displayed. When **Format Style** is **Date**, the same field takes a date instead. You will see `value`, `valueQuery`, `dateValue` and `dateValueQuery` among the flow variables: those are what the Component Builder writes depending on what you entered, not separate settings to fill in.
* **Prefix** — text displayed before the main value.
* **Suffix** — text displayed after the main value.
* **Tooltip** — text shown when the user hovers over the main value.
* **Value Sign** — controls sign display behavior: **Negative Only** (default) or **Positive and Negative**.
* **Show Trend Color** — when enabled, the main value changes color based on its relationship to the **Trend Breakpoint Value**.
* **Trend Breakpoint Value** — the threshold considered neutral for trend evaluation. Requires **Show Trend Color**.
* **Trend Icon** — icon style used to indicate trend direction: **Dynamic** (arrow that flips direction), **Arrow**, or **Caret**. Requires **Show Trend Color**.
* **Maximum Fraction Digits** and **Minimum Fraction Digits**: the most and fewest digits allowed after the decimal separator.
* **Maximum Significant Digits** and **Minimum Significant Digits**: the most and fewest significant digits allowed.
* **Minimum Integer Digits**: the fewest digits required before the decimal separator.

The five digit settings, **Show Trend Color** and its two dependent settings appear only when **Format Style** is **Decimal**, **Percent**, **Percent Fixed** or **Currency**. Under **Date**, use the date formatting options instead.

**Date formatting options** (when **Format Style** is **Date**):

* Day, Month, Year, Weekday, Era, Second, Minute, Hour, Hour 12, Timezone, Timezone Name

{% hint style="info" %}
If "Show Trend Color" is activated, it overrides the related metric's styling settings. <img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-c8afd7f097033279fc9fa892e090e57f932b74f6%2F2022-10-25_11-53-12.png?alt=media" alt="" data-size="line">
{% endhint %}

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2Fgit-blob-0caa8d24d7b1454d3e9708da5b465da06242e462%2F2024-04-19_11-49-59%20(1).gif?alt=media" alt=""><figcaption></figcaption></figure>

### Secondary Metric

Display a second value alongside the primary metric. The secondary metric offers the same settings as the primary, under their own labels: Format Style, **Secondary Value**, Prefix, Suffix, Tooltip, Value Sign, the five digit settings, Show Trend Color, Trend Breakpoint Value, Trend Icon, and the date formatting options.

* **Position**: where the secondary value appears relative to the main value: **Right** (default), **Bottom**, **Left**, or **Top**.

### Label Link

Turn the metric's label into a navigation link. Configure the **Page Reference Type** (the kind of destination — record page, object page, web page, and so on) and the matching link target. When set, clicking the label navigates to that destination.

***

## Interactions

[Interactions](/flow/component-builder/interactions-panel.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 the user clicks the primary metric value. Use this to navigate to a page, open a flow, or trigger any downstream interaction.

### Secondary Metric Click

Fires when the user clicks the secondary metric value. Use this to drive navigation or conditional logic based on 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 on the screen.

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

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

* **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="Background" %}
Sets the metric's background.

* **Color:** Set the background color.
  {% endtab %}

{% tab title="Flow Dialog" %}
Adjusts display when the metric is opened as a modal dialog inside a Flow screen.

* **Width / Height:** Dimensions of the dialog.
* **Background Color:** Dialog background color.
  {% endtab %}

{% tab title="Alignment" %}
Controls how the metric content is aligned.

* **Alignment:** Align the primary value and its label.
* **Secondary Alignment:** Align the secondary value group.
  {% endtab %}

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

* **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 additional 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 main metric value.

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

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

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

{% tab title="Suffix" %}
Styles the suffix text shown after the 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 metric 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 prefix 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 suffix 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 trend indicator colors for the primary value.

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

{% tab title="Secondary Trend" %}
Sets the trend indicator styling for the secondary value.

* **Negative / Neutral / Positive Color:** Set the secondary trend text color for each direction.
* **Negative / Neutral / Positive Background Color:** Set the secondary trend background color for each direction.
* **Negative / Neutral / Positive Radius:** Set the corner radius of the secondary trend badge for each direction.
  {% endtab %}

{% tab title="Avatar" %}
Styles the optional avatar shown with the metric.

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

***

## Output Variables

The Metric exposes these output variables you can reference in your flow after the screen. To use them, select the screen element in Flow Builder, then the Metric component, and pick the output variable you need.

### Metric Clicks

| Output variable              | Type    | What it returns                                                                 |
| ---------------------------- | ------- | ------------------------------------------------------------------------------- |
| **Primary Metric Clicked**   | Boolean | `true` when the user clicked the primary metric value during the screen step.   |
| **Secondary Metric Clicked** | Boolean | `true` when the user clicked the secondary metric value during the screen step. |

> **Example:** Show a details panel on the next screen only when the user clicked the primary value — add a Decision element that checks **Primary Metric Clicked** equals `true`.


---

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