Outstanding AR updated to $38,200, down from $42,500.
View receivablesMetric 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-secondaryvia@starting-styleand 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.
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.
<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
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.
All regions responding
Payment gateway changed from Degraded to Operational.
<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.
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.
<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 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.
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.
<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.
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.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
data-forma-value-change | the replaced value element | present (no value) | absent | Marks a freshly inserted value element as an update. Add it only to the new element the application inserts, never on first render. |
aria-live | a visually hidden paragraph | polite | — | Application-owned announcement stating the new value and, where useful, the previous one. |
aria-labelledby | article.forma-metric-card | id of the label | — | Names the card so the announcement and value are associated with a metric. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
[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__value | Element class | — | Typical host of the attribute; see Metric card. |
--forma-motion-perceptual-emphasis-duration | Custom property | — | Duration of the fade. Default 180ms (the standard primitive duration). |
--forma-motion-perceptual-easing | Custom property | — | Easing of the fade. Default cubic-bezier(0.2, 0, 0, 1). |
| Keys | Result |
|---|---|
| None | The update is not interactive and does not move focus. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Settled | no data-forma-value-change, or the fade has finished | Value on a transparent background. |
| Just updated | newly inserted element with data-forma-value-change | The value appears at once on a neutral tint that fades away. |
| Reduced motion or forced colors | prefers-reduced-motion: reduce or forced-colors: active | Transition 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: reduceand in forced-colors mode.
Your application supplies
- Replace the value element (or insert a new one) and add
data-forma-value-changeto 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-coloronly: 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: reduceandforced-colors: activethe transition isnone.
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.