Data display

Diff viewer

<forma-diff-viewer>

Before/after structured differences with explicit changed-field cues and stacked mobile comparison.

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

Purpose

A diff viewer shows two versions of a structured record side by side: a header stating what is compared and how many fields changed, then a Before and an After column, each a description list of field rows. Rows the application marks with data-change="changed" get a thick inline-start bar. On narrow screens the two columns stack into explicit Before and After sections. Forma does not compute the difference; the application decides which fields differ, in what order they appear and how added or removed values are worded.

Use when

  • Users review what changed between two versions of a record, configuration or document metadata before accepting, publishing or reverting.
  • The fields are named and each has a short value, so side-by-side reading is meaningful.
  • The comparison must remain understandable on a phone as two labelled sections.

Avoid when

  • Only the changed fields matter and each should show its before and after value together: use Comparison pairs.
  • Two concurrent edits conflict and the user must choose an outcome: use Conflict review, which composes a diff with recovery actions.
  • The change is to free text or source code line by line: show it in a Code sample or an application-specific text diff.
  • Several options are compared across many attributes: use Comparison grid.

Behavior to know

  • Two equal columns (repeat(2, minmax(0, 1fr))) separated by a subtle rule; one column at 40rem and below.
  • Each field row is a label/value grid (minmax(7rem, 0.4fr) minmax(0, 1fr)), stacking label over value at 30rem and below.
  • Changed rows get a 0.3rem accent bar on the inline start; in forced-colors mode it becomes a CanvasText bar, so the cue is structural as well as colored.
  • Only changed is styled. Added and removed values are expressed in text by the application.

Basic example

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

Canonical

Minimal diff viewer

Rendered from the canonical pattern file.

Version comparison

2 fields changed

Before

Status
Draft
Owner
Operations

After

Status
Ready for review
Owner
Operations
HTML · Minimal diff viewer Raw HTML for HTML · Minimal diff viewer
<forma-diff-viewer class="forma-component-tag">
<section class="forma-diff-viewer" aria-labelledby="diff-title">
  <header class="forma-diff-viewer__header">
    <h3 id="diff-title">Version comparison</h3>
    <p>2 fields changed</p>
  </header>
  <div class="forma-diff-viewer__grid">
    <section class="forma-diff-viewer__side" aria-label="Previous version">
      <h4>Before</h4>
      <dl>
        <div class="forma-diff-row" data-change="changed"><dt>Status</dt><dd>Draft</dd></div>
        <div class="forma-diff-row"><dt>Owner</dt><dd>Operations</dd></div>
      </dl>
    </section>
    <section class="forma-diff-viewer__side" aria-label="Current version">
      <h4>After</h4>
      <dl>
        <div class="forma-diff-row" data-change="changed"><dt>Status</dt><dd>Ready for review</dd></div>
        <div class="forma-diff-row"><dt>Owner</dt><dd>Operations</dd></div>
      </dl>
    </section>
  </div>
</section>
</forma-diff-viewer>

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

Examples

Scenario

Added and removed fields

A vendor record where one field was added, one removed and one changed. The row cue marks each difference, and the values say Not set explicitly, so an added field is not mistaken for a blank one. A visually hidden word states the change for screen-reader users.

Vendor record: revision 7 compared with revision 8

3 fields changed

Before (revision 7)

Name
Coastal Grain Cooperative
Payment terms
Net 30 (changed)
Tax exemption
Not set (added in revision 8)
Fax
+32 3 555 0142 (removed in revision 8)

After (revision 8)

Name
Coastal Grain Cooperative
Payment terms
Net 45 (changed)
Tax exemption
Certificate EX-2291 (added)
Fax
Not set (removed)
HTML · Added and removed fields Raw HTML for HTML · Added and removed fields
<forma-diff-viewer class="forma-component-tag">
  <section class="forma-diff-viewer" aria-labelledby="diff-viewer-added-and-removed-title">
    <header class="forma-diff-viewer__header">
      <h3 id="diff-viewer-added-and-removed-title">Vendor record: revision 7 compared with revision 8</h3>
      <p>3 fields changed</p>
    </header>
    <div class="forma-diff-viewer__grid">
      <section class="forma-diff-viewer__side" aria-labelledby="diff-viewer-added-and-removed-before">
        <h4 id="diff-viewer-added-and-removed-before">Before (revision 7)</h4>
        <dl>
          <div class="forma-diff-row"><dt>Name</dt><dd>Coastal Grain Cooperative</dd></div>
          <div class="forma-diff-row" data-change="changed"><dt>Payment terms</dt><dd>Net 30 <span class="forma-visually-hidden">(changed)</span></dd></div>
          <div class="forma-diff-row" data-change="changed"><dt>Tax exemption</dt><dd>Not set <span class="forma-visually-hidden">(added in revision 8)</span></dd></div>
          <div class="forma-diff-row" data-change="changed"><dt>Fax</dt><dd>+32 3 555 0142 <span class="forma-visually-hidden">(removed in revision 8)</span></dd></div>
        </dl>
      </section>
      <section class="forma-diff-viewer__side" aria-labelledby="diff-viewer-added-and-removed-after">
        <h4 id="diff-viewer-added-and-removed-after">After (revision 8)</h4>
        <dl>
          <div class="forma-diff-row"><dt>Name</dt><dd>Coastal Grain Cooperative</dd></div>
          <div class="forma-diff-row" data-change="changed"><dt>Payment terms</dt><dd>Net 45 <span class="forma-visually-hidden">(changed)</span></dd></div>
          <div class="forma-diff-row" data-change="changed"><dt>Tax exemption</dt><dd>Certificate EX-2291 <span class="forma-visually-hidden">(added)</span></dd></div>
          <div class="forma-diff-row" data-change="changed"><dt>Fax</dt><dd>Not set <span class="forma-visually-hidden">(removed)</span></dd></div>
        </dl>
      </section>
    </div>
  </section>
</forma-diff-viewer>

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

Scenario

Long values

A policy description rewritten between versions. Long values wrap inside the value column on both sides; rows on the two sides do not share heights, so keep the same field order on each side to aid comparison.

Retention policy

1 field changed

Published

Description
Evidence is kept for 30 days and then deleted automatically unless an administrator places it on hold. (changed)
Applies to
All workspaces

Draft

Description
Evidence is kept indefinitely. Exports run automatically after an approver signs off, and deletions require a second approver. (changed)
Applies to
All workspaces
HTML · Long values Raw HTML for HTML · Long values
<forma-diff-viewer class="forma-component-tag">
  <section class="forma-diff-viewer" aria-labelledby="diff-viewer-long-values-title">
    <header class="forma-diff-viewer__header">
      <h3 id="diff-viewer-long-values-title">Retention policy</h3>
      <p>1 field changed</p>
    </header>
    <div class="forma-diff-viewer__grid">
      <section class="forma-diff-viewer__side" aria-label="Published version">
        <h4>Published</h4>
        <dl>
          <div class="forma-diff-row" data-change="changed"><dt>Description</dt><dd>Evidence is kept for 30 days and then deleted automatically unless an administrator places it on hold. <span class="forma-visually-hidden">(changed)</span></dd></div>
          <div class="forma-diff-row"><dt>Applies to</dt><dd>All workspaces</dd></div>
        </dl>
      </section>
      <section class="forma-diff-viewer__side" aria-label="Draft version">
        <h4>Draft</h4>
        <dl>
          <div class="forma-diff-row" data-change="changed"><dt>Description</dt><dd>Evidence is kept indefinitely. Exports run automatically after an approver signs off, and deletions require a second approver. <span class="forma-visually-hidden">(changed)</span></dd></div>
          <div class="forma-diff-row"><dt>Applies to</dt><dd>All workspaces</dd></div>
        </dl>
      </section>
    </div>
  </section>
</forma-diff-viewer>

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 stacked comparison

At phone width the Before section is followed by the After section, each with its own heading, and each row stacks its label above its value.

Viewport width

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

What changes at narrow widths

  • At 40rem (640px) and below the grid becomes one column; the second side gets a top rule instead of a side rule.
  • At 30rem (480px) and below each .forma-diff-row stacks its label above its value.
  • Because the sides stack, the Before and After headings are what keep the comparison understandable; never omit them.
  • The changed-row bar remains on the inline start in both layouts.
  • Nothing scrolls horizontally at 320px; long values wrap.
HTML · Mobile stacked comparison Raw HTML for HTML · Mobile stacked comparison
<forma-diff-viewer class="forma-component-tag">
  <section class="forma-diff-viewer" aria-labelledby="diff-viewer-mobile-stacked-diff-title">
    <header class="forma-diff-viewer__header">
      <h3 id="diff-viewer-mobile-stacked-diff-title">Shipping address</h3>
      <p>1 field changed</p>
    </header>
    <div class="forma-diff-viewer__grid">
      <section class="forma-diff-viewer__side" aria-label="Previous address">
        <h4>Before</h4>
        <dl>
          <div class="forma-diff-row" data-change="changed"><dt>Street</dt><dd>14 Harbour Road <span class="forma-visually-hidden">(changed)</span></dd></div>
          <div class="forma-diff-row"><dt>City</dt><dd>Antwerp</dd></div>
        </dl>
      </section>
      <section class="forma-diff-viewer__side" aria-label="Current address">
        <h4>After</h4>
        <dl>
          <div class="forma-diff-row" data-change="changed"><dt>Street</dt><dd>2 Kaaiplein, Unit 5 <span class="forma-visually-hidden">(changed)</span></dd></div>
          <div class="forma-diff-row"><dt>City</dt><dd>Antwerp</dd></div>
        </dl>
      </section>
    </div>
  </section>
</forma-diff-viewer>

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-change.forma-diff-rowchangedabsent (unchanged)Marks a field row as different between versions. Written by the application on the row on both sides.
aria-labelledby.forma-diff-viewerid of the header heading—Names the comparison.
aria-label.forma-diff-viewer__sidestring—Names each side (Previous version, Current version) when the visible heading is short.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-diff-viewerBlock class—Bordered root section containing the header and the two sides.
.forma-diff-viewer__gridElement class—Two equal columns; one column at 40rem and below.
.forma-diff-viewer__headerElement class—Padded header with the comparison title and a change count; ruled below.
.forma-diff-viewer__sideElement class—One version. Padded; the second side is separated by a rule (inline on wide screens, block on narrow).
.forma-diff-rowBlock class—A field row inside a side's dl: label/value grid with a subtle bottom rule; stacks at 30rem and below.
[data-change]Attribute hook"changed"changed on .forma-diff-row adds a 0.3rem accent bar on the inline start and matching inline padding.
Keyboard interaction
KeysResult
TabReaches links or controls inside values. The viewer itself has no keyboard behavior; navigation between changes is application behavior.

Form behavior

Not a form control.

States

Diff viewer states
StateHow it is expressedPresentation
Unchanged row.forma-diff-row without data-changeLabel and value with a subtle bottom rule.
Changed rowdata-change="changed"Inline-start accent bar; CanvasText bar in forced colors.
Added or removed valueapplication text such as Not set, plus data-change="changed"No separate styling; the wording states which side lacks the value.
Stackedviewport ≤ 40remBefore and After sections stack; rows stack label over value at 30rem and below.

Accessibility

Forma provides

  • Uses sections with names and native description lists, so each side and each field is exposed with its label.
  • The changed cue is a thick bar (shape and position), not only color, and survives forced-colors mode.
  • Stacking preserves DOM order: all Before fields, then all After fields.

Your application supplies

  • Name both sides with visible headings that say which version is which.
  • State the number of changed fields in the header.
  • data-change is not announced: add text such as a visually hidden "(changed)" in changed values, or list the changes in the header.
  • Write added and removed values as text (Not set, Removed) rather than leaving a side empty.
  • If users step between changes, implement that navigation in the application and move focus to a labelled target.

Responsive behavior

  • Side by side above 40rem; stacked at 40rem and below with a block rule between sides.
  • Field rows are two-column above 30rem and stacked below it.
  • Values wrap (minmax(0, 1fr)); rows on opposite sides do not align in height when values differ in length.

Motion

  • No animation: the viewer is static and changes layout instantly at its breakpoints.

Usage guidance

Do

  • Keep the same fields in the same order on both sides.
  • Mark the row as changed on both sides so the cue lines up in the side-by-side layout.

Avoid

  • Relying on the accent bar alone to communicate a change.
  • Showing only the changed fields on one side and all fields on the other.
  • Using red and green values as the only added/removed signal.

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.