> 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/data-driven-components/metric.md).
# Metric
`avonni-dd-metric`
The Avonni Data Driven Metric displays a formatted numeric metric, with optional trend, prefix, suffix and comparison value.
## Overview
**Metric** is a data-driven Lightning Web Component that displays a formatted numeric metric, with an optional trend indicator, prefix, suffix, and comparison value.
The value is resolved from a **value query** — an aggregate query (`COUNT`, `SUM`, `AVG`, etc.) over an SObject — so the metric always reflects live data. You control number formatting (decimal, currency, percent), a secondary comparison value with its own query and trend styling, an optional avatar, tooltip, and link.
### Use Cases
* **KPIs:** Show a live count or sum, such as open cases or pipeline value.
* **Dashboards:** Combine several metrics in a row for an at-a-glance summary.
* **Trends:** Compare the primary value against a secondary value with trend color and icon.
* **Currency figures:** Format revenue or spend with a currency code.
* **Clickable metrics:** Link a metric to a report or navigate on click.
***
## Use Case Examples
### Example 1: Record count
**Scenario:** Show the total number of accounts as a labeled metric.
```html
```
```js
// accountCount.js
import { LightningElement } from 'lwc';
export default class AccountCount extends LightningElement {
accountCountQuery = {
objectApiName: 'Account',
selectedField: 'Id',
aggregateFunction: 'COUNT',
treatBlankValueAsZero: true
};
}
```
**Result:** A single formatted number labeled "Total Accounts".
### Example 2: Currency metric with a comparison trend
**Scenario:** Display total pipeline as currency, compared against a secondary value.
```html
```
```js
// pipelineMetric.js
import { LightningElement } from 'lwc';
export default class PipelineMetric extends LightningElement {
pipelineQuery = {
objectApiName: 'Opportunity',
selectedField: 'Amount',
aggregateFunction: 'SUM',
treatBlankValueAsZero: true
};
lastQuarterQuery = {
objectApiName: 'Opportunity',
selectedField: 'Amount',
aggregateFunction: 'SUM',
treatBlankValueAsZero: true
};
}
```
**Result:** A currency-formatted pipeline total with a secondary comparison value and trend coloring.
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------------------------- | -------- |
| `avatar` | Object defining the avatar attributes for the metric. | DdMetricAvatar | — | |
| `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. | Boolean | `false` | |
| `href` | URL for the primary value. If present, the primary metric is wrapped in an anchor tag linking to it. | String | — | |
| `label` | Label of the metric. If present, it will be displayed on top of the data. | String | — | |
| `label-position` | Position of the label. Valid values include `top` and `bottom`. | String | `"top"` | |
| `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 | — | |
| `refresh` | Refresh the metric values by re-running the queries. | — | — | |
| `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-href` | URL for the secondary value. If present, the secondary metric is wrapped in an anchor tag linking to it. | String | — | |
| `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. Valid values include `bottom`, `left`, `right`, and `top`. | 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` | Result of the secondary value query, as displayed to the users. | String | — | |
| `secondary-value-query` | Definition of the query to execute to get the secondary value. | DdValueQuery | — | |
| `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` | Result of the primary value query, as displayed to the users. | String | — | |
| `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 | — | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| --------- | ---------------------------------------------------- | ------------- | ------------- | -------------------- |
| `refresh` | Refresh the metric values by re-running the queries. | | | |
### 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. |
---
# 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/data-driven-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.