Data display

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

Behavior to know

  • Each .forma-comparison-pairs__item is a three-column grid: minmax(8rem, 0.8fr) for the label and two equal value columns.
  • Each value shows its data-label as a small block caption above it at every width, so values are never unlabeled.
  • data-side="before" and data-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.

Canonical

Minimal comparison pairs

Rendered from the canonical pattern file.

Configuration change

Retention
30 days
Unlimited
Export
Manual
Automated after approval
HTML · Minimal comparison pairs Raw HTML for HTML · Minimal comparison pairs
<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

Scenario

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

Customer data
Read, EU West only
Read, all regions
Exports
Up to 10,000 rows
Unlimited
Expiry
Unchanged
HTML · Access change awaiting approval Raw HTML for HTML · Access change awaiting approval
<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.

Scenario

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

Median latency
38 ms
41 ms
Last failover test
Unknown: no test recorded
HTML · Two regions compared, with an unknown value Raw HTML for HTML · Two regions compared, with an unknown value
<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 example

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.

Viewport width

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

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-label captions 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.
HTML · Mobile plan change Raw HTML for HTML · Mobile plan change
<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.

Baseline

Mobile · 320px

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

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-side.forma-comparison-pairs__valuebefore | after—Position of the value in the pair. Required for the caption to render; both values look the same.
data-label.forma-comparison-pairs__valuestring—Caption printed above the value (Before, After, Current, Proposed or a peer name). Keep it identical for every value in the same position.
aria-labelledbysection.forma-comparison-pairsid of the heading—Names the comparison.
datetimetimeISO date—Machine-readable form of date values.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-comparison-pairsBlock class—Root grid of comparison items with 1rem gaps.
.forma-comparison-pairs__itemElement class—One attribute row: label plus two value columns; single column at 30rem and below.
.forma-comparison-pairs__labelElement class—Attribute name in bold.
.forma-comparison-pairs__valueElement 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.
Keyboard interaction
KeysResult
NoneStatic content; links inside values are reached with Tab as usual.

Form behavior

Not a form control.

States

Comparison pairs states
StateHow it is expressedPresentation
Three columnsviewport > 30remLabel beside the two values.
Stackedviewport ≤ 30remLabel, first value, second value in one column, each value with its caption.
Unchanged or unknownapplication text in the valueWritten 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: 0 and overflow-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.