> 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/lwc-components/core-components/metric.md).
# Metric
`avonni-metric`
Displays a formatted numeric metric, with optional trend, prefix, suffix and comparison value.
## Overview
**Metric** is a Lightning Web Component that displays a formatted number or date as a key figure, with an optional label, secondary value, trend indicator, and avatar.
Use it in your own Lightning Web Components to surface KPIs, summary statistics, or comparison figures. You control number and date formatting, prefixes and suffixes, trend coloring, and an optional secondary value—all through the component's attributes.
### Use Cases
* **KPI tiles:** Show a headline figure like revenue, churn, or active users.
* **Trend comparisons:** Pair a primary value with a secondary year-over-year or period-over-period change.
* **Currency and percent displays:** Format values as currency or percentages with controlled fraction digits.
* **Dashboards:** Combine several metrics into a summary panel with avatars and trend colors.
* **Loading states:** Show a spinner while a value is being fetched.
***
## Format Style Guidelines
| Format Style | Use Case |
| --------------- | ------------------------------------------ |
| `decimal` | Counts and plain numbers (default). |
| `currency` | Monetary figures (set `currency-code`). |
| `percent` | Rates and ratios expressed as percentages. |
| `percent-fixed` | Values already scaled to a percentage. |
***
## Use Case Examples
### Example 1: Currency KPI with a positive trend
**Scenario:** Show annual recurring revenue with a year-over-year percent change that turns green when trending up.
```html
```
```js
// revenueMetric.js
import { LightningElement } from 'lwc';
export default class RevenueMetric extends LightningElement {
handleMetricClick() {
// Primary value clicked — e.g. navigate to the revenue report
}
}
```
**Result:** A formatted currency figure ("ARR $2,480,000") with a green "+18.2% YoY" secondary value and a dynamic trend icon.
### Example 2: Decimal metric with a loading secondary value
**Scenario:** Show active users today with the previous day's figure still loading.
```html
```
**Result:** "13,402 users" with the label below and a spinner where the secondary comparison value will appear once loaded.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------- | -------- |
| `avatar` | Avatar object. | AvonniMetricAvatar | — | |
| `currency-code` | Only used if `format-style="currency"`, this attribute determines which currency is displayed. Possible values are the ISO 4217 currency codes, such as `USD` for the US dollar. | String | — | |
| `currency-display-as` | Determines how currency is displayed. Possible values are symbol, code, and name. | String | `"symbol"` | |
| `day` | The day formatting style to use. Valid values include numeric and 2-digit. | String | — | |
| `description` | Additional text to display below the label. | String | — | |
| `era` | The era formatting style to use. Valid values include 2-digit and numeric. | String | — | |
| `error-message` | Error message text to display next to the label. | String | — | |
| `format-style` | The number formatting style to use. Possible values are decimal, currency, percent, and percent-fixed. This value defaults to decimal. | String | `"decimal"` | |
| `hour` | The hour formatting style to use. Valid values include numeric and 2-digit. | String | `"numeric"` | |
| `hour12` | Determines whether time is displayed as 12-hour. If false, time displays as 24-hour. The default setting is determined by the user's locale. Set the value using a variable. If set to any string directly, the component interprets its value as true. | Boolean | `false` | |
| `label` | Label of the metric. If present, it will be displayed on top of the data. | String | — | |
| `label-position` | Position of the label. | String | `"top"` | |
| `loading-state-alternative-text` | Message to display when the metric is in a loading state. | String | — | |
| `maximum-fraction-digits` | The maximum number of fraction digits that are allowed. | Number | — | |
| `maximum-significant-digits` | The maximum number of significant digits that are allowed. Possible values are from 1 to 21. | Number | — | |
| `minimum-fraction-digits` | The minimum number of fraction digits that are required. | Number | — | |
| `minimum-integer-digits` | The minimum number of integer digits that are required. Possible values are from 1 to 21. | Number | — | |
| `minimum-significant-digits` | The minimum number of significant digits that are required. Possible values are from 1 to 21. | Number | — | |
| `minute` | The minute formatting style to use. Valid values include numeric and 2-digit. | String | — | |
| `month` | The month formatting style to use. Valid values include 2-digit, narrow, short, long and numeric. | String | — | |
| `prefix` | Text to display before the primary value | String | — | |
| `second` | The seconds formatting style to use. Valid values include numeric and 2-digit. | String | — | |
| `secondary-currency-code` | Only used if `secondary-format-style="currency"`, this attribute determines which currency is displayed. Possible values are the ISO 4217 currency codes, such as `USD` for the US dollar. | String | — | |
| `secondary-currency-display-as` | Determines how currency is displayed. Possible values are symbol, code, and name. This value defaults to symbol. | String | `"symbol"` | |
| `secondary-day` | The day formatting style to use for the secondary value. Valid values include numeric and 2-digit. | String | — | |
| `secondary-era` | The era formatting style to use for the secondary value. Valid values include 2-digit and numeric. | String | — | |
| `secondary-format-style` | The formatting style to use for the secondary value. Possible values are decimal, currency, percent, and percent-fixed. | String | `"decimal"` | |
| `secondary-hour` | The hour formatting style to use for the secondary value. Valid values include numeric and 2-digit. | String | — | |
| `secondary-hour12` | Determines whether time is displayed as 12-hour for the secondary value. | Boolean | — | |
| `secondary-maximum-fraction-digits` | The maximum number of fraction digits that are allowed. | Number | — | |
| `secondary-maximum-significant-digits` | The maximum number of significant digits that are allowed. Possible values are from 1 to 21. | Number | — | |
| `secondary-minimum-fraction-digits` | The minimum number of fraction digits that are required. | Number | — | |
| `secondary-minimum-integer-digits` | The minimum number of integer digits that are required. Possible values are from 1 to 21. | Number | — | |
| `secondary-minimum-significant-digits` | The minimum number of significant digits that are required. Possible values are from 1 to 21. | Number | — | |
| `secondary-minute` | The minute formatting style to use for the secondary value. Valid values include numeric and 2-digit. | String | — | |
| `secondary-month` | The month formatting style to use for the secondary value. Valid values include 2-digit, narrow, short, long and numeric. | String | — | |
| `secondary-position` | Position of the secondary value, relative to the value. | String | `"right"` | |
| `secondary-prefix` | Text to display before the secondary value. | String | — | |
| `secondary-second` | The seconds formatting style to use for the secondary value. Valid values include numeric and 2-digit. | String | — | |
| `secondary-show-trend-color` | If present, the secondary value will change color and background depending on the trend direction. | Boolean | `false` | |
| `secondary-suffix` | Text to display after the secondary value. | String | — | |
| `secondary-time-zone` | Time zone used for the seconday value, in a valid IANA format. | String | `"Current user's time zone"` | |
| `secondary-time-zone-name` | The time zone name format to use for the secondary value. Valid values include short and long. | String | — | |
| `secondary-trend-breakpoint-value` | Number at which the secondary value will be considered neutral. Works in association with `secondary-trend-icon` and `secondary-show-trend-color`. | Number | `0` | |
| `secondary-trend-icon` | Type of icon indicating the trend direction of the secondary value. Valid values include dynamic, arrow and caret. | String | — | |
| `secondary-value` | If present, a secondary number or date will be displayed to the right of the primary one. | String | — | |
| `secondary-value-is-loading` | If present, a spinner is displayed to indicate that the secondary value is loading. | Boolean | `false` | |
| `secondary-value-sign` | Determine what signs are allowed to be displayed in front of the secondary value, to indicate that it is positive or negative. Valid values include negative, positive-and-negative or none. | String | `"negative"` | |
| `secondary-weekday` | The weekday formatting style to use for the secondary value. Valid values include narrow, short and long. | String | — | |
| `secondary-year` | The year formatting style to use for the secondary value. Valid values include 2-digit and numeric. | String | — | |
| `show-trend-color` | If present, the value will change color depending on the trend direction. | Boolean | `false` | |
| `suffix` | Text to display after the primary value. | String | — | |
| `time-zone` | Time zone used for the primary value, in a valid IANA format. | String | `"Current user's time zone"` | |
| `time-zone-name` | The time zone name format to use. Valid values include short and long. | String | — | |
| `tooltip` | Text to display when the user mouses over the value. | String | — | |
| `trend-breakpoint-value` | Number at which the value will be considered neutral. Works in association with `trend-icon` and `show-trend-color`. | Number | `0` | |
| `trend-icon` | Type of icon indicating the trend direction of the value. Valid values include dynamic, arrow and caret. | String | — | |
| `value` | Value of the primary metric. Can be a number or a date. | String | — | |
| `value-is-loading` | If present, a spinner is displayed to indicate that the value is loading. | Boolean | `false` | |
| `value-sign` | Determine what signs are allowed to be displayed in front of the value, to indicate that it is positive or negative. Valid values include negative, positive-and-negative or none. | String | `"negative"` | |
| `weekday` | The weekday formatting style to use. Valid values include narrow, short and long. | String | — | |
| `year` | The year formatting style to use. Valid values include 2-digit and numeric. | String | — | |
### Custom Events
#### `metricclick`
The event fired when the primary metric is clicked.
The `metricclick` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `secondarymetricclick`
The event fired when the secondary metric is clicked.
The `secondarymetricclick` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
### Styling Hooks
| CSS Variable | Type | Default |
| ----------------------------------------------------------- | --------- | ------------ |
| `--avonni-metric-alignment` | alignment | `left` |
| `--avonni-metric-avatar-vertical-alignment` | alignment | `flex-start` |
| `--avonni-metric-cursor` | string | `text` |
| `--avonni-metric-description-font-size` | dimension | `0.75rem` |
| `--avonni-metric-description-font-style` | font | `normal` |
| `--avonni-metric-description-font-weight` | (string | number) |
| `--avonni-metric-description-line-clamp` | integer | `2` |
| `--avonni-metric-description-text-color` | color | `#747474` |
| `--avonni-metric-label-font-size` | dimension | `0.875rem` |
| `--avonni-metric-label-font-style` | font | `normal` |
| `--avonni-metric-label-line-clamp` | integer | `1` |
| `--avonni-metric-label-text-color` | color | `#444444` |
| `--avonni-metric-negative-trend-text-color` | color | `#ba0517` |
| `--avonni-metric-neutral-trend-text-color` | color | `#444444` |
| `--avonni-metric-prefix-font-size` | dimension | `1rem` |
| `--avonni-metric-prefix-font-style` | font | `normal` |
| `--avonni-metric-prefix-font-weight` | (string | number) |
| `--avonni-metric-prefix-text-color` | color | `#181818` |
| `--avonni-metric-secondary-alignment` | string | — |
| `--avonni-metric-secondary-cursor` | string | `text` |
| `--avonni-metric-secondary-negative-trend-color-background` | color | `#feded8` |
| `--avonni-metric-secondary-negative-trend-radius` | dimension | `0.25rem` |
| `--avonni-metric-secondary-negative-trend-text-color` | color | `#ba0517` |
| `--avonni-metric-secondary-neutral-trend-color-background` | color | `#f3f3f3` |
| `--avonni-metric-secondary-neutral-trend-radius` | dimension | `0.25rem` |
| `--avonni-metric-secondary-neutral-trend-text-color` | color | `#181818` |
| `--avonni-metric-secondary-positive-trend-color-background` | color | `#cdefc4` |
| `--avonni-metric-secondary-positive-trend-radius` | dimension | `0.25rem` |
| `--avonni-metric-secondary-positive-trend-text-color` | color | `#2e844a` |
| `--avonni-metric-secondary-prefix-font-size` | dimension | `0.8125rem` |
| `--avonni-metric-secondary-prefix-font-style` | font | `normal` |
| `--avonni-metric-secondary-prefix-font-weight` | (string | number) |
| `--avonni-metric-secondary-prefix-text-color` | color | `#444444` |
| `--avonni-metric-secondary-suffix-font-size` | dimension | `0.8125rem` |
| `--avonni-metric-secondary-suffix-font-style` | font | `normal` |
| `--avonni-metric-secondary-suffix-font-weight` | (string | number) |
| `--avonni-metric-secondary-suffix-text-color` | color | `#444444` |
| `--avonni-metric-secondary-value-font-size` | dimension | `0.8125rem` |
| `--avonni-metric-secondary-value-font-style` | font | `normal` |
| `--avonni-metric-secondary-value-font-weight` | (string | number) |
| `--avonni-metric-secondary-value-text-color` | color | `#444444` |
| `--avonni-metric-suffix-font-size` | dimension | `1rem` |
| `--avonni-metric-suffix-font-style` | font | `normal` |
| `--avonni-metric-suffix-font-weight` | (string | number) |
| `--avonni-metric-suffix-text-color` | color | `#181818` |
| `--avonni-metric-value-font-size` | dimension | `1.5rem` |
| `--avonni-metric-value-font-style` | font | `normal` |
| `--avonni-metric-value-font-weight` | (string | number) |
| `--avonni-metric-value-line-height` | number | `1.25` |
| `--avonni-metric-value-text-color` | color | `#181818` |
| `--avonni-metric-positive-trend-text-color` | color | `#2e844a` |
| `--avonni-metric-label-font-weight` | font | `normal` |
## Key Considerations
* **Value type:** `value` accepts both numbers and dates; date formatting attributes (e.g. `year`, `month`, `day`) apply when the value is a date.
* **Trend coloring:** `show-trend-color` and `trend-icon` use `trend-breakpoint-value` (default `0`) to decide positive, neutral, or negative.
* **Secondary value:** The secondary value has its own full set of formatting, trend, and loading attributes, prefixed with `secondary-`.
* **Loading states:** Use `value-is-loading` or `secondary-value-is-loading` to show spinners while data is fetched.
* **Best Practice:** Match `format-style` to the data (currency, percent) and use `trend-icon` with `show-trend-color` so the direction of change is immediately readable.
***
## Troubleshooting Common Issues
* **Currency not formatting:** Set both `format-style="currency"` and a valid `currency-code` (e.g. `USD`).
* **Trend color not showing:** Confirm `show-trend-color` is present and the value crosses `trend-breakpoint-value` in the expected direction.
* **Click event not firing:** Wire `onmetricclick` (or `onsecondarymetricclick`) in the template; both events bubble.
* **If issues persist:** Contact our support team at for assistance.
---
# 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/lwc-components/core-components/metric.md?ask=&goal=
```
`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.