Data display

Comparison grid

<forma-comparison-grid>

Preserves cross-item comparison relationships in a bounded two-dimensional surface.

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

Purpose

A comparison grid is a native table with items as columns and attributes as row headers, inside a focusable, labelled region that scrolls horizontally when the table is wider than its container. The table is sized to its content (min-inline-size: max-content), so columns are never squeezed or recomposed: reading across a row always compares the same attribute. Forma provides the bounded surface and cell spacing; the application supplies the items, attributes and wording, including explicit Not included and Unknown cells.

Use when

  • Three or more items (plans, vendors, releases) are compared across the same attributes.
  • Keeping rows and columns aligned matters more than avoiding horizontal scrolling on phones.
  • Each cell is a short value or phrase.

Avoid when

  • Only two items are compared: use Comparison pairs, which stays readable on phones without scrolling.
  • Rows are records the user acts on: use Data grid.
  • The table is an expert ledger of many entries: use Dense ledger.
  • The comparison is a marketing pricing layout with prominent calls to action: compose Card grid or Call to action instead of styling table cells as cards.

Behavior to know

  • The region scrolls horizontally with overscroll-behavior-inline: contain, so a sideways swipe does not scroll the page.
  • The table uses min-inline-size: max-content: columns take the width their content needs.
  • Cells are start-aligned and top-aligned with 0.75rem padding.
  • The focused region shows a 2px outline in the current text color.

Basic example

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

Canonical

Minimal comparison grid

Rendered from the canonical pattern file.

Plan comparison
CapabilityStandardAdvanced
Evidence history30 daysUnlimited
ExportsManualAutomated
HTML · Minimal comparison grid Raw HTML for HTML · Minimal comparison grid
<forma-comparison-grid class="forma-component-tag">
<div class="forma-comparison-grid" role="region" aria-label="Plan comparison" tabindex="0">
  <table>
    <caption>Plan comparison</caption>
    <thead><tr><th scope="col">Capability</th><th scope="col">Standard</th><th scope="col">Advanced</th></tr></thead>
    <tbody><tr><th scope="row">Evidence history</th><td>30 days</td><td>Unlimited</td></tr><tr><th scope="row">Exports</th><td>Manual</td><td>Automated</td></tr></tbody>
  </table>
</div>
</forma-comparison-grid>

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

Examples

Scenario

Not included and unknown values

Three support tiers. Missing capabilities say Not included, and a value the vendor has not published says Unknown, so an empty cell never has to be interpreted.

Support tier comparison
CapabilityBasicBusinessEnterprise
First response2 business days8 hours1 hour
Phone supportNot includedBusiness hours24 × 7
Named engineerNot includedNot includedIncluded
Uptime commitmentNone99.9%Unknown: contract specific
HTML · Not included and unknown values Raw HTML for HTML · Not included and unknown values
<forma-comparison-grid class="forma-component-tag">
  <div class="forma-comparison-grid" role="region" aria-label="Support tier comparison" tabindex="0">
    <table>
      <caption>Support tier comparison</caption>
      <thead><tr><th scope="col">Capability</th><th scope="col">Basic</th><th scope="col">Business</th><th scope="col">Enterprise</th></tr></thead>
      <tbody>
        <tr><th scope="row">First response</th><td>2 business days</td><td>8 hours</td><td>1 hour</td></tr>
        <tr><th scope="row">Phone support</th><td>Not included</td><td>Business hours</td><td>24 × 7</td></tr>
        <tr><th scope="row">Named engineer</th><td>Not included</td><td>Not included</td><td>Included</td></tr>
        <tr><th scope="row">Uptime commitment</th><td>None</td><td>99.9%</td><td>Unknown: contract specific</td></tr>
      </tbody>
    </table>
  </div>
</forma-comparison-grid>

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

Scenario

Wide vendor comparison

Five vendors across four attributes is wider than most containers. The table keeps every column at its content width and the region scrolls sideways within its own bounds instead of widening the page. The row headers stay first in each row so every value can be traced to its attribute.

Freight vendor comparison, Q4 quotes
AttributeNorthline FreightBaltic CarriersRhein LogistikAtlas Shipping GroupCoastal Haulage
Rate per pallet€142€128€151€119€135
Transit, Rotterdam to Lyon3 days4 days2 days5 days3 days
Customs brokerageIncludedExtra chargeIncludedNot offeredExtra charge
Insurance limit€250,000€100,000€500,000Unknown€250,000
HTML · Wide vendor comparison Raw HTML for HTML · Wide vendor comparison
<forma-comparison-grid class="forma-component-tag">
  <div class="forma-comparison-grid" role="region" aria-label="Freight vendor comparison" tabindex="0">
    <table>
      <caption>Freight vendor comparison, Q4 quotes</caption>
      <thead>
        <tr><th scope="col">Attribute</th><th scope="col">Northline Freight</th><th scope="col">Baltic Carriers</th><th scope="col">Rhein Logistik</th><th scope="col">Atlas Shipping Group</th><th scope="col">Coastal Haulage</th></tr>
      </thead>
      <tbody>
        <tr><th scope="row">Rate per pallet</th><td>€142</td><td>€128</td><td>€151</td><td>€119</td><td>€135</td></tr>
        <tr><th scope="row">Transit, Rotterdam to Lyon</th><td>3 days</td><td>4 days</td><td>2 days</td><td>5 days</td><td>3 days</td></tr>
        <tr><th scope="row">Customs brokerage</th><td>Included</td><td>Extra charge</td><td>Included</td><td>Not offered</td><td>Extra charge</td></tr>
        <tr><th scope="row">Insurance limit</th><td>€250,000</td><td>€100,000</td><td>€500,000</td><td>Unknown</td><td>€250,000</td></tr>
      </tbody>
    </table>
  </div>
</forma-comparison-grid>

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

Three releases compared on a phone. The table keeps its shape and the region scrolls horizontally; nothing collapses.

Viewport width

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

What changes at narrow widths

  • The grid never recomposes. When the table is wider than the screen the region scrolls horizontally inside itself and the page does not overflow at 320px.
  • overscroll-behavior-inline: contain keeps a sideways swipe inside the grid instead of scrolling the page or triggering back navigation.
  • The region is focusable (tabindex="0"), so keyboard and switch users can scroll it; it shows a 2px outline when focused.
  • Put the attribute column first; it scrolls with the table, so short attribute names keep the context visible longer.
  • Landscape orientation fits more columns and reduces scrolling; nothing else changes.
HTML · Mobile release comparison Raw HTML for HTML · Mobile release comparison
<forma-comparison-grid class="forma-component-tag">
  <div class="forma-comparison-grid" role="region" aria-label="Release comparison" tabindex="0">
    <table>
      <caption>Release comparison</caption>
      <thead><tr><th scope="col">Check</th><th scope="col">2026.08</th><th scope="col">2026.09</th><th scope="col">2026.10 candidate</th></tr></thead>
      <tbody>
        <tr><th scope="row">Tests</th><td>Passed</td><td>Passed</td><td>2 failing</td></tr>
        <tr><th scope="row">Security review</th><td>Complete</td><td>Complete</td><td>Not started</td></tr>
      </tbody>
    </table>
  </div>
</forma-comparison-grid>

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
role.forma-comparison-gridregion—Makes the scroll container a named landmark.
aria-label.forma-comparison-gridstring—Names the region, usually the same as the table caption.
tabindex.forma-comparison-grid0—Lets keyboard users focus and scroll the region.
scopethcol | row—col on item headers, row on attribute headers, so each cell is announced with both.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-comparison-gridBlock class—The bounded scroll region around the native table: horizontal overflow, inline overscroll containment and a focus outline. The inner table is sized to max-content and its cells are padded, start-aligned and top-aligned.
Keyboard interaction
KeysResult
TabFocuses the region.
Arrow keysScroll the focused region natively. There is no cell navigation.

Form behavior

Not a form control.

States

Comparison grid states
StateHow it is expressedPresentation
Fitstable width ≤ region widthThe table fills the region at full width.
Overflowingtable wider than the regionThe region scrolls horizontally; the page does not.
Focused:focus-visible on the region2px outline in the current text color, offset by 2px.
Not included / Unknown cellapplication textStated in words; no special styling.

Accessibility

Forma provides

  • Keeps a native table so row and column headers are announced with each cell.
  • Never hides or reorders columns, so the comparison is identical for every user and width.
  • Shows a visible focus indicator on the scroll region.

Your application supplies

  • Provide a caption, scope on every header, and a matching aria-label on the region.
  • Write every cell; use Not included, None or Unknown rather than blanks, dashes or check-mark icons without text.
  • Do not mark a recommended or winning column by color alone; say so in the header text.

Responsive behavior

  • No breakpoints; the table keeps its content width and the region scrolls horizontally when needed.
  • Long cell text can make columns very wide because the table is max-content; keep cell text short or insert natural break points.
  • For two items on phones, Comparison pairs avoids scrolling entirely.

Motion

  • No animation: the grid is static. Scrolling is native and follows user settings.

Usage guidance

Do

  • Put items in columns and attributes in rows, with the attribute column first.
  • Keep units in the attribute header or every value.

Avoid

  • Icons-only cells (check marks and crosses) without text.
  • Very long prose in cells, which widens the whole column.

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.