Metric Card

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

MetricCard is exported from @prepared911/ui. It composes CardHeader and CardContent. It does not export MetricValue, MetricChange, or private chrome helpers.

Props

Name	Type	Default	Description
`label`	`LocalizedMessage \| DisplayValue`	—	The metric's name. Always a heading, so the dashboard outline names every tile.
`value`	`number \| LocalizedMessage \| DisplayValue \| null`	—	The metric. Each change rolls the digits that changed. The metric as copy or data. No value.
`announcement`	`LocalizedMessage`	—	Copy a polite live region announces after a change of `value` has settled. Not announced on first paint. Text does not roll. An empty value does not roll.
`aria-label`	`LocalizedMessage \| DisplayValue`	—	A static card has no action to name. Accessible name of the action ("Show queue depth"). The overlay button carries it.
`aria-pressed`	`boolean`	—	A static card has no action to toggle. Toggle state. Omit for a plain action; `true` paints the accent edge.
`children`	`undefined`	—	The card is a closed preset. It takes no children.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`controls`	`ReactNode`	—	Interactive group in the header, such as a SegmentedControl. An action card holds no other interactive control.
`delta`	`MetricCardDelta`	—	The change beside the value. An empty value has nothing to compare.
`emptyLabel`	`LocalizedMessage`	—	A numeric value has no empty-state copy. A text value has no empty-state copy. Names the gap for assistive technology ("No calls today").
`emptyText`	`LocalizedMessage`	—	A numeric value has no empty-state placeholder. A text value has no empty-state placeholder. Visible placeholder. Omit it for an em dash.
`formatOptions`	`NumberFormatOptions`	—	`Intl.NumberFormat` options: currency, percent, units, compact notation, fraction digits, sign display. Text is not formatted. An empty value is not formatted.
`from`	`number`	—	Entrance: the first paint shows this number, then the digits roll to `value`. Read on mount only. Text does not roll. An empty value does not roll.
`headingLevel`	`CardHeadingLevel`	`CardHeadingLevel.H3`	Heading element for the label. The label's type role is fixed, so the rank follows the page outline.
`loading`	`boolean`	—	Replace the value, delta, subtitle and sparkline with a skeleton and mark the body busy. Show the value and delta.
`loadingLabel`	`LocalizedMessage`	—	The one loading status assistive technology reads. Visually hidden: the skeleton is the visible cue. A card that is not loading has no loading copy.
`locale`	`string`	—	BCP 47 locale for the value and the delta. Defaults to the runtime locale, so a server-rendered page that must match the client passes it explicitly.
`onClick`	`MouseEventHandler<HTMLButtonElement>`	—	A static card has no action. Runs when the card is activated by pointer, Enter or Space.
`prefix`	`TextAffix`	—	Localized copy before the number, or a function of the number that returns it. Include any separating space. Text is not formatted. An empty value is not formatted.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the card's root element.
`roll`	`boolean`	`true`	Roll the digits of the value and the delta to each new number. `false` renders them as plain formatted text and drops `from` and `announcement`.
`size`	`MetricCardSize`	`MetricCardSize.Default`	Padding and value type.
`sparkline`	`ReactNode`	—	Slot for a sparkline from Charts. Mounted `aria-hidden` in a fixed-height box under the value, so it must repeat nothing the value, delta and subtitle do not already say.
`subtitle`	`LocalizedMessage \| DisplayValue`	—	Supporting copy under the value, such as the period the value covers.
`suffix`	`TextAffix`	—	Localized copy after the number, or a function of the number that returns it. Include any separating space. Text is not formatted. An empty value is not formatted.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Exact contract

Name	Type	Notes
`label`	`LocalizedMessage`	Required. Rendered as `CardHeader` title.
`value`	`LocalizedMessage` or `number`	Always NumericDisplay (2.4rem) with tabular figures, rendered as a `span`. Numeric values use `formatNumber`. Prelocalized messages skip number formatting and animation.
`subtitle`	`LocalizedMessage`	Optional.
`formatOptions`	`Intl.NumberFormatOptions`	Numeric values only.
`headingLevel`	`HeadingLevel`	Optional. Semantic rank for the header title. Default `HeadingLevel.H3`. Does not change value typography.
`from` / `announcement` / `roll`	see below	Numeric values roll through `Text` value mode.
`delta`	`MetricCardDelta`	Mutually exclusive with `trailing`. Optional visual-only delta animation.
`trailing`	`ReactNode`	Decorative, `aria-hidden`, 2.8rem box. Omitted when unset or a boolean. Forbidden when `delta` is set.
`loading`	`boolean`	Requires `loadingLabel`.
`controls`	`ReactNode`	Forwarded to `CardHeader.controls`. Mutually exclusive with clickable props.
`onClick` / `selected` / `aria-label`	see interaction	Activates the stretched card action target. Requires all three when clickable.

Value animation

A numeric value rolls through Text from @prepared911/ui/text:

from is the entrance number. It is read on mount only.
announcement is localized copy spoken after a change of value settles.
roll={false} renders the formatted number as plain text.
A value that is already copy does not roll.

Delta magnitudes accept visual-only animation without polite live regions.

Delta model

Direction and tone are separate fields. Direction selects the arrow; tone colors the delta label and arrow fill only.

`direction`	Arrow	Magnitude	Tone
`Increase` / `Decrease` / `Unchanged`	Yes	Required numeric value	Required
`Introduced` / `Unavailable`	No	Unrepresentable	Unrepresentable; use `label`

There is no card-level tone or statusLabel.

Default tile

Stat card with delta

Animated value and delta

Clickable tile

Decorative trailing chart

Use ChartFamilyDemos on the visualization-charts page. MetricCard trailing is aria-hidden; the label and value are the equivalent. Do not pass trailing when delta is set.

Metric Card / Usage

Metric Card / Accessibility

On this page

Animated value and delta

Clickable tile

Decorative trailing chart

Metric Card

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

MetricCard is exported from @prepared911/ui. It composes CardHeader and CardContent. It does not export MetricValue, MetricChange, or private chrome helpers.

Props

Name	Type	Default	Description
`label`	`LocalizedMessage \| DisplayValue`	—	The metric's name. Always a heading, so the dashboard outline names every tile.
`value`	`number \| LocalizedMessage \| DisplayValue \| null`	—	The metric. Each change rolls the digits that changed. The metric as copy or data. No value.
`announcement`	`LocalizedMessage`	—	Copy a polite live region announces after a change of `value` has settled. Not announced on first paint. Text does not roll. An empty value does not roll.
`aria-label`	`LocalizedMessage \| DisplayValue`	—	A static card has no action to name. Accessible name of the action ("Show queue depth"). The overlay button carries it.
`aria-pressed`	`boolean`	—	A static card has no action to toggle. Toggle state. Omit for a plain action; `true` paints the accent edge.
`children`	`undefined`	—	The card is a closed preset. It takes no children.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`controls`	`ReactNode`	—	Interactive group in the header, such as a SegmentedControl. An action card holds no other interactive control.
`delta`	`MetricCardDelta`	—	The change beside the value. An empty value has nothing to compare.
`emptyLabel`	`LocalizedMessage`	—	A numeric value has no empty-state copy. A text value has no empty-state copy. Names the gap for assistive technology ("No calls today").
`emptyText`	`LocalizedMessage`	—	A numeric value has no empty-state placeholder. A text value has no empty-state placeholder. Visible placeholder. Omit it for an em dash.
`formatOptions`	`NumberFormatOptions`	—	`Intl.NumberFormat` options: currency, percent, units, compact notation, fraction digits, sign display. Text is not formatted. An empty value is not formatted.
`from`	`number`	—	Entrance: the first paint shows this number, then the digits roll to `value`. Read on mount only. Text does not roll. An empty value does not roll.
`headingLevel`	`CardHeadingLevel`	`CardHeadingLevel.H3`	Heading element for the label. The label's type role is fixed, so the rank follows the page outline.
`loading`	`boolean`	—	Replace the value, delta, subtitle and sparkline with a skeleton and mark the body busy. Show the value and delta.
`loadingLabel`	`LocalizedMessage`	—	The one loading status assistive technology reads. Visually hidden: the skeleton is the visible cue. A card that is not loading has no loading copy.
`locale`	`string`	—	BCP 47 locale for the value and the delta. Defaults to the runtime locale, so a server-rendered page that must match the client passes it explicitly.
`onClick`	`MouseEventHandler<HTMLButtonElement>`	—	A static card has no action. Runs when the card is activated by pointer, Enter or Space.
`prefix`	`TextAffix`	—	Localized copy before the number, or a function of the number that returns it. Include any separating space. Text is not formatted. An empty value is not formatted.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the card's root element.
`roll`	`boolean`	`true`	Roll the digits of the value and the delta to each new number. `false` renders them as plain formatted text and drops `from` and `announcement`.
`size`	`MetricCardSize`	`MetricCardSize.Default`	Padding and value type.
`sparkline`	`ReactNode`	—	Slot for a sparkline from Charts. Mounted `aria-hidden` in a fixed-height box under the value, so it must repeat nothing the value, delta and subtitle do not already say.
`subtitle`	`LocalizedMessage \| DisplayValue`	—	Supporting copy under the value, such as the period the value covers.
`suffix`	`TextAffix`	—	Localized copy after the number, or a function of the number that returns it. Include any separating space. Text is not formatted. An empty value is not formatted.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Exact contract

Name	Type	Notes
`label`	`LocalizedMessage`	Required. Rendered as `CardHeader` title.
`value`	`LocalizedMessage` or `number`	Always NumericDisplay (2.4rem) with tabular figures, rendered as a `span`. Numeric values use `formatNumber`. Prelocalized messages skip number formatting and animation.
`subtitle`	`LocalizedMessage`	Optional.
`formatOptions`	`Intl.NumberFormatOptions`	Numeric values only.
`headingLevel`	`HeadingLevel`	Optional. Semantic rank for the header title. Default `HeadingLevel.H3`. Does not change value typography.
`from` / `announcement` / `roll`	see below	Numeric values roll through `Text` value mode.
`delta`	`MetricCardDelta`	Mutually exclusive with `trailing`. Optional visual-only delta animation.
`trailing`	`ReactNode`	Decorative, `aria-hidden`, 2.8rem box. Omitted when unset or a boolean. Forbidden when `delta` is set.
`loading`	`boolean`	Requires `loadingLabel`.
`controls`	`ReactNode`	Forwarded to `CardHeader.controls`. Mutually exclusive with clickable props.
`onClick` / `selected` / `aria-label`	see interaction	Activates the stretched card action target. Requires all three when clickable.

Value animation

A numeric value rolls through Text from @prepared911/ui/text:

from is the entrance number. It is read on mount only.
announcement is localized copy spoken after a change of value settles.
roll={false} renders the formatted number as plain text.
A value that is already copy does not roll.

Delta magnitudes accept visual-only animation without polite live regions.

Delta model

Direction and tone are separate fields. Direction selects the arrow; tone colors the delta label and arrow fill only.

`direction`	Arrow	Magnitude	Tone
`Increase` / `Decrease` / `Unchanged`	Yes	Required numeric value	Required
`Introduced` / `Unavailable`	No	Unrepresentable	Unrepresentable; use `label`

There is no card-level tone or statusLabel.

Default tile

Stat card with delta

Animated value and delta

Clickable tile

Decorative trailing chart

Use ChartFamilyDemos on the visualization-charts page. MetricCard trailing is aria-hidden; the label and value are the equivalent. Do not pass trailing when delta is set.

Metric Card / Usage

Metric Card / Accessibility

On this page

Animated value and delta

Clickable tile

Decorative trailing chart