Data display

Metric card

<forma-metric-card>

A compact labeled value with context and optional action, without inventing metric meaning.

Authoring tag
<forma-metric-card>
Category
Data display
Behavior owner
Application content
Canonical source
patterns/metric-card.html

Purpose

A metric card shows one application-supplied number or short value with its label, optional context and an optional link to the underlying records. Forma gives the card a border, a secondary-colored label and a large display-type value that scales with the viewport. It never computes, compares, colors by trend or interprets the value: whether a number is good, bad, stale or unknown is text the application writes.

Use when

  • A dashboard or overview needs a few headline values users check at a glance, such as open work or outstanding receivables.
  • Each value has a clear label and, where needed, context such as the period, freshness or a status in words.
  • A value leads to a list or report the user can open for detail.

Avoid when

  • The value updates live and the update should be marked: use Metric value change, which adds the neutral update tint and live announcement.
  • Several related values about one record are shown: use Key-value list.
  • The number is a proportion of a known range users need to judge: show it with a native meter or a Progress bar.
  • The value needs its derivation explained: pair the card with a Provenance trail rather than packing it into the card.

Behavior to know

  • The value uses the display font at clamp(2rem, 8vw, 3.5rem) with a line-height of 1, so it scales down on phones.
  • Label, value and any following content stack in a single grid column with 0.5rem gaps.
  • The card is min-inline-size: 0, so it can shrink inside Dashboard grid or Responsive grid columns.
  • No color is applied to the value; direction and state must be written as text.

Basic example

The smallest correct markup: the canonical pattern from patterns/metric-card.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal metric card

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Minimal metric card Raw HTML for HTML · Minimal metric card
<forma-metric-card class="forma-component-tag">
<article class="forma-metric-card">
  <div class="forma-metric-card__label">Outstanding AR</div>
  <div class="forma-metric-card__value">$42,500</div>
  <div class="forma-metric-card__context"><span class="forma-status-lozenge" data-state="attention">$12,500 overdue</span></div>
  <a href="#details">View receivables</a>
</article>
</forma-metric-card>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Value not available

The metric source is unavailable. The card shows the word Unknown instead of zero or a dash, and a sentence says why, so a missing number is never read as a real one.

Failed payments today
Unknown

Source unavailable

The payment processor feed has not reported since 06:00 UTC.

HTML · Value not available Raw HTML for HTML · Value not available
<forma-metric-card class="forma-component-tag">
  <article class="forma-metric-card" aria-labelledby="metric-card-unknown-value-label">
    <div class="forma-metric-card__label" id="metric-card-unknown-value-label">Failed payments today</div>
    <div class="forma-metric-card__value">Unknown</div>
    <p><span class="forma-status-lozenge" data-state="unknown">Source unavailable</span></p>
    <p>The payment processor feed has not reported since 06:00 UTC.</p>
  </article>
</forma-metric-card>

Click or tap the code once to select all of it, then copy.

Scenario

Value with freshness and period

The value is stated with its period and a Freshness line, so users can tell how current it is. A trend is written as words ("down 4 from last week"), not as a green or red arrow.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Open incidents, last 7 days
12

Down 4 from the previous 7 days.

Last updated Stale: refresh overdue by 2 hours

View incidents
HTML · Value with freshness and period Raw HTML for HTML · Value with freshness and period
<forma-metric-card class="forma-component-tag">
  <article class="forma-metric-card" aria-labelledby="metric-card-stale-with-freshness-label">
    <div class="forma-metric-card__label" id="metric-card-stale-with-freshness-label">Open incidents, last 7 days</div>
    <div class="forma-metric-card__value">12</div>
    <p>Down 4 from the previous 7 days.</p>
    <p class="forma-freshness"><span class="forma-freshness__label">Last updated</span> <time datetime="2026-09-29T05:00:00Z">05:00 UTC</time> <span>Stale: refresh overdue by 2 hours</span></p>
    <a href="#metric-card-stale-with-freshness-incidents">View incidents</a>
  </article>
</forma-metric-card>

Click or tap the code once to select all of it, then copy.

Scenario

Dashboard row with long labels

Three cards in a Dashboard grid. Labels of different lengths wrap inside their cards; the value scale stays the same across cards, so no value looks more important than another.

Outstanding receivables across all subsidiaries
$1,204,500

As of 29 Sep 2026.

Overdue
$212,040

31 invoices past due.

Disputed
0

No open disputes.

HTML · Dashboard row with long labels Raw HTML for HTML · Dashboard row with long labels
<forma-metric-card class="forma-component-tag">
  <section class="forma-dashboard-grid" aria-label="Receivables overview">
    <article class="forma-metric-card"><div class="forma-metric-card__label">Outstanding receivables across all subsidiaries</div><div class="forma-metric-card__value">$1,204,500</div><p>As of 29 Sep 2026.</p></article>
    <article class="forma-metric-card"><div class="forma-metric-card__label">Overdue</div><div class="forma-metric-card__value">$212,040</div><p>31 invoices past due.</p></article>
    <article class="forma-metric-card"><div class="forma-metric-card__label">Disputed</div><div class="forma-metric-card__value">0</div><p>No open disputes.</p></article>
  </section>
</forma-metric-card>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile metric stack

Two cards at phone width. The value shrinks toward its 2rem minimum and each card keeps its label, context and link in reading order.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The value size follows clamp(2rem, 8vw, 3.5rem): about 2rem at 320px and 390px, reaching 3.5rem only at wide viewports.
  • Inside Dashboard grid the cards collapse to one column at 40rem and below, keeping the application's order.
  • Long labels and context text wrap; the card has min-inline-size: 0 so it never forces horizontal scrolling.
  • The trailing link is an ordinary inline link; keep its text descriptive so it is a usable tap target on its own line.
  • Rotation only changes the value's viewport-relative size between the clamp bounds.
HTML · Mobile metric stack Raw HTML for HTML · Mobile metric stack
<forma-metric-card class="forma-component-tag">
  <div class="forma-stack" data-density="compact">
    <article class="forma-metric-card">
      <div class="forma-metric-card__label">Needs attention</div>
      <div class="forma-metric-card__value">7</div>
      <p><span class="forma-status-lozenge" data-state="attention">3 overdue</span></p>
      <a href="#metric-card-mobile-metric-stack-attention">Open attention queue</a>
    </article>
    <article class="forma-metric-card">
      <div class="forma-metric-card__label">Completed this month</div>
      <div class="forma-metric-card__value">42</div>
      <p>Through 29 September.</p>
    </article>
  </div>
</forma-metric-card>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelledbyarticle.forma-metric-cardid of .forma-metric-card__label—Names the card by its label when several cards appear together.
datetimetimeISO date-time—Machine-readable update time in freshness context.
hrefaURL—Optional link to the records behind the value.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-metric-cardBlock class—The card root, usually an article. Bordered grid with 1.25rem padding and 0.5rem gaps; shrinkable to zero width.
.forma-metric-card__labelElement class—The metric's label in secondary text color, 0.8125rem, semibold.
.forma-metric-card__valueElement class—The value in the display font at clamp(2rem, 8vw, 3.5rem), line-height 1.
Keyboard interaction
KeysResult
TabReaches the optional link or button in the card. The card itself is not focusable.

Form behavior

Not a form control.

States

Metric card states
StateHow it is expressedPresentation
Known valueapplication text in .forma-metric-card__valueThe number or short value in display type.
Unknown or unavailableapplication text such as Unknown plus contextForma has no special styling; the words carry the state.
Stalecontext text, for example a Freshness lineThe age of the value is stated next to it.
Updateddata-forma-value-change on the value (see Metric value change)A neutral tint briefly marks an application-published update.

Accessibility

Forma provides

  • Label and value are real text in reading order, so screen readers read the label before the value.
  • The value has no color coding, so meaning never depends on hue.
  • Text uses semantic color tokens that map to system colors in forced-colors mode.

Your application supplies

  • Name the card with aria-labelledby on the label when cards are presented as a group.
  • Write units, period and direction as text ("Down 4 from last week").
  • Show Unknown, Unavailable or Stale explicitly; never substitute zero.
  • Give links descriptive text rather than "More".

Responsive behavior

  • Intrinsic width: the card shrinks to its container (min-inline-size: 0).
  • The value scales with the viewport between 2rem and 3.5rem.
  • Arrange several cards with Dashboard grid (three columns, one at 40rem and below) or Responsive grid.
  • Very long unbroken values can still exceed a narrow card; keep values short or format them with separators.

Motion

  • No animation on the card itself. Marking a live update is the separate Metric value change contract, which tints the value with a neutral perceptual fade and never counts through numbers.

Usage guidance

Do

  • Pair each value with its period and, for live data, its freshness.
  • Link to the records behind the number when users will want to act on it.

Avoid

  • Coloring the value green or red to imply good or bad.
  • Animating numbers counting up; show the authoritative value immediately.
  • Showing zero or a dash when the value is unknown.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.