VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Comparison pairs
<forma-comparison-pairs>
Before/after or peer comparison that repeats labels and preserves the comparison task when columns collapse on narrow screens.
- Authoring tag
<forma-comparison-pairs>- Category
- Data display
- Behavior owner
- Application content
- Canonical source
patterns/comparison-pairs.html
Purpose
Comparison pairs show, for each attribute, two values next to each other: the attribute label, then a first and a second value. Each value prints its own small label from data-label (Before/After, Current/Proposed, or two peer names), so the comparison survives when the three columns collapse into one on a phone. Forma provides the layout and the repeated labels; the application decides which attributes are shown and what the values mean.
Use when
- A few attributes change between a current and a proposed state and the user must confirm the change.
- Two peers (plans, regions, candidates) are compared attribute by attribute.
- The comparison must stay intact on narrow screens where a table would either scroll or lose its column headers.
Avoid when
- Whole versions of a record are compared with every field listed on each side: use Diff viewer.
- More than two items are compared: use Comparison grid.
- Only one value per label is shown: use Key-value list.
- The user must choose between conflicting versions: use Conflict review.
Behavior to know
- Each
.forma-comparison-pairs__itemis a three-column grid:minmax(8rem, 0.8fr)for the label and two equal value columns. - Each value shows its
data-labelas a small block caption above it at every width, so values are never unlabeled. data-side="before"anddata-side="after"are what enable the caption; both sides are styled identically, so neither looks preferred.- At 30rem and below each item becomes a single column: label, first value, second value.
Basic example
The smallest correct markup: the canonical pattern from patterns/comparison-pairs.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal comparison pairs
Rendered from the canonical pattern file.
Configuration change
<forma-comparison-pairs class="forma-component-tag">
<section class="forma-comparison-pairs" aria-labelledby="comparison-pairs-title">
<h3 id="comparison-pairs-title">Configuration change</h3>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Retention</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Before">30 days</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="After">Unlimited</div>
</div>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Export</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Before">Manual</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="After">Automated after approval</div>
</div>
</section>
</forma-comparison-pairs>
Click or tap the code once to select all of it, then copy.
Examples
Access change awaiting approval
Current and proposed permissions for a service account. The captions say Current and Proposed; an unchanged attribute is still listed so the reviewer sees the full scope of the account.
svc-export: requested access change
<forma-comparison-pairs class="forma-component-tag">
<section class="forma-comparison-pairs" aria-labelledby="comparison-pairs-access-change-title">
<h3 id="comparison-pairs-access-change-title">svc-export: requested access change</h3>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Customer data</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Current">Read, EU West only</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="Proposed">Read, all regions</div>
</div>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Exports</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Current">Up to 10,000 rows</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="Proposed">Unlimited</div>
</div>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Expiry</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Current"><time datetime="2027-01-31">31 Jan 2027</time></div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="Proposed">Unchanged</div>
</div>
</section>
</forma-comparison-pairs>
Click or tap the code once to select all of it, then copy.
Two regions compared, with an unknown value
A peer comparison of two data regions. The captions are the region names, and a value the application cannot supply is written as Unknown rather than left blank. data-side here only selects the first and second position.
EU West compared with US East
<forma-comparison-pairs class="forma-component-tag">
<section class="forma-comparison-pairs" aria-labelledby="comparison-pairs-peer-regions-title">
<h3 id="comparison-pairs-peer-regions-title">EU West compared with US East</h3>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Median latency</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="EU West">38 ms</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="US East">41 ms</div>
</div>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Last failover test</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="EU West"><time datetime="2026-09-12">12 Sep 2026</time></div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="US East">Unknown: no test recorded</div>
</div>
</section>
</forma-comparison-pairs>
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 plan change
A subscription change at phone width. Each attribute becomes a small stack: the attribute name, then the Before value with its caption, then the After value with its caption.
What changes at narrow widths
- At 30rem (480px) and below each item switches to a single column: label, first value, second value, in DOM order.
- The
data-labelcaptions are what keep the pairs understandable once the columns are gone; they appear at every width. - Values wrap anywhere (
overflow-wrap: anywhere), so long identifiers or addresses do not overflow at 320px. - The component has no interactive parts; put confirm or cancel actions after it at full width.
<forma-comparison-pairs class="forma-component-tag">
<section class="forma-comparison-pairs" aria-labelledby="comparison-pairs-mobile-plan-change-title">
<h3 id="comparison-pairs-mobile-plan-change-title">Review plan change</h3>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Plan</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Before">Team</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="After">Business</div>
</div>
<div class="forma-comparison-pairs__item">
<div class="forma-comparison-pairs__label">Monthly price</div>
<div class="forma-comparison-pairs__value" data-side="before" data-label="Before">$480.00</div>
<div class="forma-comparison-pairs__value" data-side="after" data-label="After">$1,150.00</div>
</div>
</section>
</forma-comparison-pairs>
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.
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-side | .forma-comparison-pairs__value | before | after | — | Position of the value in the pair. Required for the caption to render; both values look the same. |
data-label | .forma-comparison-pairs__value | string | — | Caption printed above the value (Before, After, Current, Proposed or a peer name). Keep it identical for every value in the same position. |
aria-labelledby | section.forma-comparison-pairs | id of the heading | — | Names the comparison. |
datetime | time | ISO date | — | Machine-readable form of date values. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-comparison-pairs | Block class | — | Root grid of comparison items with 1rem gaps. |
.forma-comparison-pairs__item | Element class | — | One attribute row: label plus two value columns; single column at 30rem and below. |
.forma-comparison-pairs__label | Element class | — | Attribute name in bold. |
.forma-comparison-pairs__value | Element class | — | One value. Shrinkable, wraps anywhere, and prints its data-label caption above itself. |
[data-side] | Attribute hook | "after", "before" | before or after on a value enables the data-label caption via ::before. |
| Keys | Result |
|---|---|
| None | Static content; links inside values are reached with Tab as usual. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Three columns | viewport > 30rem | Label beside the two values. |
| Stacked | viewport ≤ 30rem | Label, first value, second value in one column, each value with its caption. |
| Unchanged or unknown | application text in the value | Written as words (Unchanged, Unknown); no special styling. |
Accessibility
Forma provides
- Repeats the side caption with every value, so the comparison is understandable without column headers.
- Styles both sides identically, so neither the old nor the new value is visually favored.
- Keeps DOM order label, first value, second value at every width.
Your application supplies
- The captions come from CSS generated content, which some assistive technologies do not announce reliably. Where the side matters, also include it in the text or use a heading that states the order (for example "Current, then proposed").
- Give the section a heading that says what is being compared.
- Write unchanged, removed and unknown values explicitly.
- Do not signal better or worse through color; state it in text if it matters.
Responsive behavior
- Three columns above 30rem; one column at 30rem and below.
- Values have
min-inline-size: 0andoverflow-wrap: anywhere, so they never force horizontal scrolling. - The label column has an 8rem minimum on wide layouts; long attribute names wrap within it.
Motion
- No animation: the component is static and switches layout instantly at 30rem.
Usage guidance
Do
- Keep captions short and consistent down the list.
- List only the attributes the decision depends on, plus any unchanged ones needed for scope.
Avoid
- Omitting
data-side; without it the caption does not render. - Using comparison pairs for more than two items.
- Highlighting the proposed value as if it were already approved.
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.