Layout primitives

Grid

<forma-grid>

Foundation auto-fit grid that fills columns by a minimum track width and collapses to one column without media queries.

Authoring tag
<forma-grid>
Behavior owner
Native CSS
Canonical source
patterns/grid.html

Purpose

The foundation grid lays out peer items in as many equal columns as fit, given a minimum track width. When the container narrows, columns drop one at a time until a single column remains; no media query is involved, so the grid reflows by the space it actually has, whether it sits in a full page, a sidebar or a dialog. It is the default choice for collections of comparable things: environments, plans, summary panels, option cards.

Use when

  • A collection of peer items should align into columns and reflow by available width.
  • The number of items varies with data and the column count should follow from the space, not be fixed.
  • A dashboard region needs equal-weight panels that stay readable at any container width.

Avoid when

  • One item needs to span columns for emphasis: use Responsive grid, which adds span helpers and narrow-screen collapse rules.
  • An editorial layout needs deliberately uneven spans on a fixed four-column rhythm: use Mosaic.
  • Items are metrics in an operational dashboard with its own conventions: use Dashboard grid.
  • Data has rows and columns that must be compared cell by cell: use a table in Bounded overflow or Data grid.

Behavior to know

  • Columns come from repeat(auto-fit, minmax(min(100%, var(--forma-grid-min)), 1fr)), so a track is never wider than the container.
  • Items fill rows in source order; the grid never reorders them.
  • The grid draws nothing; pair it with Surface items when each cell needs a boundary.

Basic example

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

Canonical

Minimal grid

Rendered from the canonical pattern file.

  • Production

    12 services, all reporting.

  • Staging

    12 services, 1 deploying.

  • Development

    9 services, 3 idle.

HTML · Minimal grid Raw HTML for HTML · Minimal grid
<forma-grid class="forma-component-tag">
<ul class="forma-grid" aria-label="Environments" role="list">
  <li class="forma-surface"><h3>Production</h3><p>12 services, all reporting.</p></li>
  <li class="forma-surface"><h3>Staging</h3><p>12 services, 1 deploying.</p></li>
  <li class="forma-surface"><h3>Development</h3><p>9 services, 3 idle.</p></li>
</ul>
</forma-grid>

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

Examples

Scenario

Plan comparison

Three plan panels with a wider minimum track (--forma-grid-min: 18rem) so each panel keeps a readable measure. The panels sit in three columns on a wide screen and drop to fewer columns as the container narrows.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

  • Starter

    Up to 5 people, community support, 10 GB storage.

  • Team

    Up to 50 people, business-hours support, 1 TB storage and audit log export.

  • Enterprise

    Unlimited people, single sign-on, dedicated support and data residency options.

HTML · Plan comparison Raw HTML for HTML · Plan comparison
<forma-grid class="forma-component-tag">
  <ul class="forma-grid" role="list" aria-label="Plans" style="--forma-grid-min: 18rem">
    <li class="forma-surface forma-stack" data-density="compact">
      <h2>Starter</h2>
      <p>Up to 5 people, community support, 10 GB storage.</p>
      <button type="button">Choose Starter</button>
    </li>
    <li class="forma-surface forma-stack" data-density="compact">
      <h2>Team</h2>
      <p>Up to 50 people, business-hours support, 1 TB storage and audit log export.</p>
      <button type="button">Choose Team</button>
    </li>
    <li class="forma-surface forma-stack" data-density="compact">
      <h2>Enterprise</h2>
      <p>Unlimited people, single sign-on, dedicated support and data residency options.</p>
      <button type="button">Talk to sales</button>
    </li>
  </ul>
</forma-grid>

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

Scenario

Analytical monitoring tiles

Six service tiles under data-density="analytical" with a narrow minimum track. The tighter gap keeps more tiles in view for monitoring; each tile still states its status in text.

  • API gateway

    Healthy

  • Auth

    Healthy

  • Billing

    Degraded

  • Search

    Healthy

  • Exports

    No data

  • Webhooks

    Paused

HTML · Analytical monitoring tiles Raw HTML for HTML · Analytical monitoring tiles
<forma-grid class="forma-component-tag">
  <ul class="forma-grid" role="list" aria-label="Service health" data-density="analytical" style="--forma-grid-min: 11rem">
    <li class="forma-surface"><h2>API gateway</h2><p><span class="forma-status-lozenge" data-state="ok">Healthy</span></p></li>
    <li class="forma-surface"><h2>Auth</h2><p><span class="forma-status-lozenge" data-state="ok">Healthy</span></p></li>
    <li class="forma-surface"><h2>Billing</h2><p><span class="forma-status-lozenge" data-state="attention">Degraded</span></p></li>
    <li class="forma-surface"><h2>Search</h2><p><span class="forma-status-lozenge" data-state="ok">Healthy</span></p></li>
    <li class="forma-surface"><h2>Exports</h2><p><span class="forma-status-lozenge" data-state="unknown">No data</span></p></li>
    <li class="forma-surface"><h2>Webhooks</h2><p><span class="forma-status-lozenge" data-state="blocked">Paused</span></p></li>
  </ul>
</forma-grid>

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

Scenario

Single result

A grid holding one item. auto-fit collapses the empty tracks, so the lone item stretches across the row instead of sitting in a narrow first column.

  • Production (eu-west)

    Only one environment matches the filter "eu".

HTML · Single result Raw HTML for HTML · Single result
<forma-grid class="forma-component-tag">
  <ul class="forma-grid" role="list" aria-label="Matching environments">
    <li class="forma-surface"><h2>Production (eu-west)</h2><p>Only one environment matches the filter "eu".</p></li>
  </ul>
</forma-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 environment list

Four environment panels at phone width. Because the minimum track is larger than half the screen, the grid is a single column.

Viewport width

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

What changes at narrow widths

  • With the default 16rem minimum, 320px and 390px screens fit only one track, so items stack in source order.
  • min(100%, var(--forma-grid-min)) keeps a track from ever exceeding the container, so there is no horizontal scroll even when the minimum is wider than the screen.
  • In landscape on a phone two columns may fit; the change is driven by available width, not device type.
  • Each item is full width, so links and buttons inside keep generous touch areas.
HTML · Mobile environment list Raw HTML for HTML · Mobile environment list
<forma-grid class="forma-component-tag">
  <ul class="forma-grid" role="list" aria-label="Environments on this account">
    <li class="forma-surface"><h2>Production</h2><p>12 services, all reporting.</p></li>
    <li class="forma-surface"><h2>Staging</h2><p>12 services, 1 deploying.</p></li>
    <li class="forma-surface"><h2>Preview</h2><p>4 short-lived environments from open pull requests.</p></li>
    <li class="forma-surface"><h2>Development</h2><p>9 services, 3 idle.</p></li>
  </ul>
</forma-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
roleul.forma-gridlist—Restores list semantics that some browsers drop when list styling is removed. Keep it when the grid is a ul or ol.
aria-label.forma-gridstring—Names the collection so screen-reader users know what the list contains.
data-density.forma-gridrelaxed | standard | compact | analyticalabsent (1rem gap)Contextual density posture. Sets the gap to 1.5rem, 1rem, or 0.5rem (compact and analytical). Not a data-forma-* hook; it changes spacing only.
style.forma-grid--forma-grid-min / --forma-grid-gap—Per-instance override of the minimum track width or the gap.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-gridBlock class—Auto-fit grid of equal columns sized by a minimum track width.
[data-density]Attribute hook—Density posture on the grid. relaxed = 1.5rem, standard = 1rem, compact and analytical = 0.5rem gap. Overrides --forma-grid-gap.
--forma-grid-gapCustom property—Gap between rows and columns. Default --forma-primitive-spacing-4 (1rem).
--forma-grid-minCustom property—Minimum track width before a column is dropped. Default 16rem. Clamped to 100% of the container.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through focusable content row by row in source order. The grid is not an ARIA grid and has no arrow-key navigation.

Form behavior

Not a form control.

States

Grid states
StateHow it is expressedPresentation
Multi-columncontainer wider than two minimum tracksItems fill as many equal columns as fit.
Single columncontainer narrower than two minimum tracksItems stack at full width in source order.
Density posturedata-density attributeGap follows the posture instead of --forma-grid-gap.

Accessibility

Forma provides

  • Placement follows source order, so reading and focus order match the visual rows.
  • Tracks never exceed the container, so the grid itself does not cause horizontal scrolling at 320px or 400% zoom.
  • Adds no role; .forma-grid on a list keeps list semantics when role="list" is present.

Your application supplies

  • Use a list (ul or ol with role="list") when the items are a collection, and name it with aria-label.
  • Give each item a heading or other text so identity does not depend on its column position.
  • Do not use role="grid" for this layout; it is not an interactive data grid.

Responsive behavior

  • Container-driven: the column count is computed from the grid's own inline size, so the same grid reflows correctly inside a narrow sidebar on a wide screen.
  • No media queries. At phone widths the default 16rem minimum yields one column.
  • auto-fit collapses empty tracks, so a short collection stretches its items to fill the row.
  • Items inherit min-inline-size from their own styles; Surface sets min-inline-size: 0, so long words wrap instead of widening the track.

Motion

  • No animation: columns reflow instantly when the width changes.

Usage guidance

Do

  • Set --forma-grid-min from the content: the narrowest width at which one item is still readable.
  • Use data-density rather than a custom gap when the whole region's posture changes.

Avoid

  • Encoding priority or rank through column position; screen readers hear only source order.
  • Setting a fixed column count; let the minimum track decide.

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.