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.

<!-- revenueMetric.html -->
<template>
    <avonni-metric
        currency-code="USD"
        description="Compared to the same period last year."
        format-style="currency"
        label="Annual Recurring Revenue"
        maximum-fraction-digits="0"
        prefix="ARR"
        secondary-format-style="percent"
        secondary-prefix="("
        secondary-suffix=" YoY)"
        secondary-show-trend-color
        secondary-trend-icon="dynamic"
        secondary-value="0.182"
        secondary-value-sign="positive-and-negative"
        show-trend-color
        trend-icon="dynamic"
        value="2480000"
        onmetricclick={handleMetricClick}
    ></avonni-metric>
</template>

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

<!-- activeUsersMetric.html -->
<template>
    <avonni-metric
        label="Active Users Today"
        label-position="bottom"
        secondary-prefix="vs "
        secondary-suffix=" yesterday"
        secondary-value="12940"
        secondary-value-is-loading
        suffix=" users"
        value="13402"
    ></avonni-metric>
</template>

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

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 [email protected] for assistance.