Data display

Metric value change

<forma-metric-value-change>

A metric whose authoritative value updates immediately; a neutral perceptual tint marks the update without counting through invented numbers or implying direction.

Authoring tag
<forma-metric-value-change>
Category
Data display
Behavior owner
Application state
Canonical source
patterns/metric-value-change.html

Purpose

When the application publishes a new value for a metric, it replaces the value element and marks the new element with data-forma-value-change. The new text is fully legible from the first frame; Forma only fades a neutral surface tint from behind it. The tint is the same for increases, decreases and status changes, so motion never implies direction, success or severity. What changed, and by how much, is stated in text and announced by an application-owned polite live region.

Use when

  • A metric or status value on screen is replaced while the user is looking at it, for example after polling or a push update.
  • Users should notice that a value changed without the change being dramatized.
  • The previous value matters and can be stated in an announcement or context line.

Avoid when

  • The value is rendered for the first time on page load: render it without the attribute, as a plain Metric card.
  • Progress toward completion is shown: use Progress bar, which projects the authoritative value directly.
  • The change needs the user's decision or is an error: use Alert or Operation status rather than a transient tint.
  • The goal is to show movement over time: show the history in a Timeline or a chart with a text equivalent.

Behavior to know

  • No count-through: the element only ever contains the final value, so no invented intermediate numbers appear.
  • The tint starts at --forma-color-surface-secondary via @starting-style and fades to transparent; text contrast is unaffected at every frame.
  • Works on any element: the selector is :where([data-forma-value-change]), with zero specificity so component styles still win.
  • Under reduced motion and in forced-colors mode there is no transition; the new value simply appears.

Basic example

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

Canonical

Minimal metric value change

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.

Outstanding AR
$38,200
$8,200 overdue

Outstanding AR updated to $38,200, down from $42,500.

View receivables
HTML · Minimal metric value change Raw HTML for HTML · Minimal metric value change
<forma-metric-value-change class="forma-component-tag">
<article class="forma-metric-card" aria-labelledby="metric-ar-label">
  <div class="forma-metric-card__label" id="metric-ar-label">Outstanding AR</div>
  <!-- The application replaced this element with the new authoritative value
       and marked it data-forma-value-change; the text is current immediately. -->
  <div class="forma-metric-card__value" data-forma-value-change>$38,200</div>
  <div class="forma-metric-card__context"><span class="forma-status-lozenge" data-state="attention">$8,200 overdue</span></div>
  <p class="forma-visually-hidden" aria-live="polite">Outstanding AR updated to $38,200, down from $42,500.</p>
  <a href="#details">View receivables</a>
</article>
</forma-metric-value-change>

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

Examples

Scenario

Status value changed

A non-numeric metric changes from Degraded to Operational. The replaced value receives the same neutral tint a number would, and the live region states the old and new values in words.

Payment gateway
Operational

All regions responding

Payment gateway changed from Degraded to Operational.

HTML · Status value changed Raw HTML for HTML · Status value changed
<forma-metric-value-change class="forma-component-tag">
  <article class="forma-metric-card" aria-labelledby="metric-value-change-status-change-label">
    <div class="forma-metric-card__label" id="metric-value-change-status-change-label">Payment gateway</div>
    <div class="forma-metric-card__value" data-forma-value-change>Operational</div>
    <p><span class="forma-status-lozenge" data-state="ok">All regions responding</span></p>
    <p class="forma-visually-hidden" aria-live="polite">Payment gateway changed from Degraded to Operational.</p>
  </article>
</forma-metric-value-change>

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

Scenario

Updated value in a detail list

The attribute is not limited to metric cards. Here one value in a Key-value list was replaced after a sync; only that dd is marked, and the other rows stay still.

Warehouse stock

SKU
BRK-2210
On hand
186 units
Reserved
40 units

On hand updated to 186 units, down from 240.

HTML · Updated value in a detail list Raw HTML for HTML · Updated value in a detail list
<forma-metric-value-change class="forma-component-tag">
  <section aria-labelledby="metric-value-change-detail-value-update-title">
    <h3 id="metric-value-change-detail-value-update-title">Warehouse stock</h3>
    <dl class="forma-key-value-list">
      <div><dt>SKU</dt><dd><span class="forma-identifier">BRK-2210</span></dd></div>
      <div><dt>On hand</dt><dd data-forma-value-change>186 units</dd></div>
      <div><dt>Reserved</dt><dd>40 units</dd></div>
    </dl>
    <p class="forma-visually-hidden" aria-live="polite">On hand updated to 186 units, down from 240.</p>
  </section>
</forma-metric-value-change>

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 updated metric

A metric card at phone width right after an update. The tint covers only the value element; layout does not move when the value is replaced.

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 tint is background color only; no position, size or opacity changes, so nothing shifts on a small screen.
  • The value keeps the metric card's clamp(2rem, 8vw, 3.5rem) size. A longer new value wraps onto a new line rather than overflowing.
  • The polite live region announces the change on phones with a screen reader, independent of whether the tint was seen.
  • Orientation changes do not re-trigger the tint; it only runs when the application inserts a new marked element.
HTML · Mobile updated metric Raw HTML for HTML · Mobile updated metric
<forma-metric-value-change class="forma-component-tag">
  <article class="forma-metric-card" aria-labelledby="metric-value-change-mobile-updated-metric-label">
    <div class="forma-metric-card__label" id="metric-value-change-mobile-updated-metric-label">Open incidents</div>
    <div class="forma-metric-card__value" data-forma-value-change>5</div>
    <p>Was 6 at 09:10 UTC.</p>
    <p class="forma-visually-hidden" aria-live="polite">Open incidents updated to 5, down from 6.</p>
    <a href="#metric-value-change-mobile-updated-metric-incidents">View incidents</a>
  </article>
</forma-metric-value-change>

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
data-forma-value-changethe replaced value elementpresent (no value)absentMarks a freshly inserted value element as an update. Add it only to the new element the application inserts, never on first render.
aria-livea visually hidden paragraphpolite—Application-owned announcement stating the new value and, where useful, the previous one.
aria-labelledbyarticle.forma-metric-cardid of the label—Names the card so the announcement and value are associated with a metric.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
[data-forma-value-change]Attribute hook—Presence starts a neutral background tint (--forma-color-surface-secondary) that fades to transparent over --forma-motion-perceptual-emphasis-duration. Zero specificity; applies to any element.
.forma-metric-card__valueElement class—Typical host of the attribute; see Metric card.
--forma-motion-perceptual-emphasis-durationCustom property—Duration of the fade. Default 180ms (the standard primitive duration).
--forma-motion-perceptual-easingCustom property—Easing of the fade. Default cubic-bezier(0.2, 0, 0, 1).
Keyboard interaction
KeysResult
NoneThe update is not interactive and does not move focus.

Form behavior

Not a form control.

States

Metric value change states
StateHow it is expressedPresentation
Settledno data-forma-value-change, or the fade has finishedValue on a transparent background.
Just updatednewly inserted element with data-forma-value-changeThe value appears at once on a neutral tint that fades away.
Reduced motion or forced colorsprefers-reduced-motion: reduce or forced-colors: activeTransition removed; the new value appears with no emphasis motion.

Accessibility

Forma provides

  • The new value is the element's only text from the first frame, at full opacity and full contrast.
  • The emphasis is identical for every kind of change, so it carries no meaning that color-blind or low-vision users would miss.
  • Removes the transition under prefers-reduced-motion: reduce and in forced-colors mode.

Your application supplies

  • Replace the value element (or insert a new one) and add data-forma-value-change to the new element; toggling the attribute on an existing element does not replay @starting-style.
  • Announce meaningful changes in a polite live region, including direction and previous value in words.
  • Throttle announcements for values that update frequently so the live region does not chatter.
  • Keep any status text (for example a Status lozenge) in sync with the value in the same update.

Responsive behavior

  • No layout change: the tint is a background color on the existing box.
  • Behaves the same at every width and orientation; the host component (for example Metric card) owns sizing.

Motion

  • Perceptual interpolation of background-color only: from --forma-color-surface-secondary (via @starting-style) to transparent over --forma-motion-perceptual-emphasis-duration (180ms) with --forma-motion-perceptual-easing.
  • No spatial motion and no mass: the value does not slide, scale, fade in or count through intermediate numbers.
  • The same fade is used for increases, decreases, unchanged republishes and status changes.
  • A second update replaces the element again and restarts the fade from the new element; nothing queues.
  • Under prefers-reduced-motion: reduce and forced-colors: active the transition is none.

Usage guidance

Do

  • Mark only the value that changed, not the whole card or page.
  • State the change in words where it matters ("down from 240").

Avoid

  • Adding the attribute on initial render, which makes every value flash on load.
  • Coloring the tint by direction or adding arrows that animate.
  • Using the tint as the only signal for a change the user must act on.

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.