Data display

Data grid

<forma-data-grid>

Semantic tabular records with sortable-column affordances, contained horizontal overflow and a labeled record projection on phones.

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

Purpose

A data grid presents a set of records as a native table inside a focusable, labelled scroll region. Forma styles the header, cells, sort indicators and the narrow-screen recomposition: at 30rem and below the header row is hidden and every cell prints its own data-label, so each row reads as a labelled record. Forma does not sort, filter, select, paginate or navigate cells. Header buttons are plain native buttons; the application (normally through Limen) decides what activating them does and writes the resulting aria-sort.

Use when

  • Users scan, compare and act on many records that share the same fields, such as invoices, tickets or deployments.
  • Columns can be sorted by the application and the current sort must be visible and announced.
  • Each row carries a small number of row-level actions such as Open or Review.
  • The same records must remain usable on a 320px phone without horizontal page scrolling.

Avoid when

  • The table is dense expert reference data where column alignment must survive on phones: use Dense ledger inside Bounded overflow, which keeps the table shape.
  • Only a handful of labelled facts about one object are shown: use Key-value list.
  • The user compares a few items across the same attributes and must keep rows and columns aligned: use Comparison grid.
  • Rows are unresolved work items whose main purpose is the next action: use Work queue.
  • Cells are editable or the grid needs arrow-key cell navigation: that requires an application-owned role="grid" keyboard model, which Forma does not provide.

Behavior to know

  • The table keeps a 42rem minimum width, so on tablets the region scrolls horizontally inside its own border instead of squeezing columns.
  • At 30rem and below each row becomes a bordered record and each cell a two-column label/value grid driven by data-label.
  • The sort direction is shown by an arrow appended to the header button from aria-sort, so the visual and the accessibility tree share one source.
  • Status is expected to be text (for example a Status lozenge), never cell color alone.

Basic example

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

Canonical

Minimal data grid

Rendered from the canonical pattern file.

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.

Invoice records
Actions
INV-1042 Acme Manufacturing Oct 4, 2026 Overdue
INV-1043 Northstar Labs Oct 18, 2026 Current
HTML · Minimal data grid Raw HTML for HTML · Minimal data grid
<forma-data-grid class="forma-component-tag">
<div class="forma-data-grid" role="region" tabindex="0" aria-label="Invoice records">
  <table>
    <caption class="forma-visually-hidden">Invoice records</caption>
    <thead>
      <tr>
        <th scope="col" aria-sort="ascending"><button type="button">Invoice</button></th>
        <th scope="col"><button type="button">Customer</button></th>
        <th scope="col"><button type="button">Due</button></th>
        <th scope="col"><button type="button">Status</button></th>
        <th scope="col"><span class="forma-visually-hidden">Actions</span></th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td data-label="Invoice">INV-1042</td>
        <td data-label="Customer">Acme Manufacturing</td>
        <td data-label="Due">Oct 4, 2026</td>
        <td data-label="Status"><span class="forma-status-lozenge" data-state="attention">Overdue</span></td>
        <td data-label="Actions"><button type="button">Open</button></td>
      </tr>
      <tr>
        <td data-label="Invoice">INV-1043</td>
        <td data-label="Customer">Northstar Labs</td>
        <td data-label="Due">Oct 18, 2026</td>
        <td data-label="Status"><span class="forma-status-lozenge" data-state="ok">Current</span></td>
        <td data-label="Actions"><button type="button">Open</button></td>
      </tr>
    </tbody>
  </table>
</div>
</forma-data-grid>

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

Examples

Scenario

Sorted by due date, newest first

The application has sorted by Due in descending order, so only that header carries aria-sort="descending" and shows a down arrow. Row actions name their record so a list of Open buttons is not ambiguous out of context.

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.

Invoices sorted by due date, newest first
Actions
INV-1051 Harbor Freight Partners Draft
INV-1047 Northstar Labs Payment unconfirmed
INV-1042 Acme Manufacturing Overdue
HTML · Sorted by due date, newest first Raw HTML for HTML · Sorted by due date, newest first
<forma-data-grid class="forma-component-tag">
  <div class="forma-data-grid" role="region" tabindex="0" aria-label="Invoices by due date">
    <table>
      <caption class="forma-visually-hidden">Invoices sorted by due date, newest first</caption>
      <thead>
        <tr>
          <th scope="col"><button type="button">Invoice</button></th>
          <th scope="col"><button type="button">Customer</button></th>
          <th scope="col" aria-sort="descending"><button type="button">Due</button></th>
          <th scope="col"><button type="button">Status</button></th>
          <th scope="col"><span class="forma-visually-hidden">Actions</span></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td data-label="Invoice">INV-1051</td>
          <td data-label="Customer">Harbor Freight Partners</td>
          <td data-label="Due"><time datetime="2026-11-02">Nov 2, 2026</time></td>
          <td data-label="Status"><span class="forma-status-lozenge">Draft</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open INV-1051">Open</button></td>
        </tr>
        <tr>
          <td data-label="Invoice">INV-1047</td>
          <td data-label="Customer">Northstar Labs</td>
          <td data-label="Due"><time datetime="2026-10-18">Oct 18, 2026</time></td>
          <td data-label="Status"><span class="forma-status-lozenge" data-state="unknown">Payment unconfirmed</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open INV-1047">Open</button></td>
        </tr>
        <tr>
          <td data-label="Invoice">INV-1042</td>
          <td data-label="Customer">Acme Manufacturing</td>
          <td data-label="Due"><time datetime="2026-10-04">Oct 4, 2026</time></td>
          <td data-label="Status"><span class="forma-status-lozenge" data-state="attention">Overdue</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open INV-1042">Open</button></td>
        </tr>
      </tbody>
    </table>
  </div>
</forma-data-grid>

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

Scenario

Empty result

The query returned no records. The header row stays so the columns still explain what would appear, and an Empty state after the region says why the table is empty and how to recover. Forma does not decide between empty, loading and failed; the application renders the right one.

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.

Overdue invoices

No overdue invoices

Every invoice due before today has been paid or written off.

HTML · Empty result Raw HTML for HTML · Empty result
<forma-data-grid class="forma-component-tag">
  <div class="forma-stack" data-density="compact">
    <div class="forma-data-grid" role="region" tabindex="0" aria-label="Overdue invoices">
      <table>
        <caption class="forma-visually-hidden">Overdue invoices</caption>
        <thead>
          <tr>
            <th scope="col"><button type="button">Invoice</button></th>
            <th scope="col"><button type="button">Customer</button></th>
            <th scope="col" aria-sort="ascending"><button type="button">Due</button></th>
            <th scope="col"><button type="button">Status</button></th>
          </tr>
        </thead>
        <tbody></tbody>
      </table>
    </div>
    <section class="forma-empty-state" aria-labelledby="data-grid-empty-result-title">
      <div class="forma-empty-state__symbol" aria-hidden="true">□</div>
      <h3 id="data-grid-empty-result-title">No overdue invoices</h3>
      <p>Every invoice due before today has been paid or written off.</p>
      <button type="button">Show all invoices</button>
    </section>
  </div>
</forma-data-grid>

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

Scenario

Many columns and long values

Seven columns exceed a tablet-width container, so the table scrolls inside the labelled region rather than widening the page. The region is focusable, so keyboard users can scroll it with the arrow keys. Long customer names wrap inside their cells.

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.

Shipment records
Actions
SHP-2026-000418 Rheinland Präzisionswerkzeuge und Industriebedarf GmbH Rotterdam, NL Duisburg, DE 12,480 kg Delivered
SHP-2026-000419 Coastal Grain Cooperative Antwerp, BE Lyon, FR — Held at customs
HTML · Many columns and long values Raw HTML for HTML · Many columns and long values
<forma-data-grid class="forma-component-tag">
  <div class="forma-data-grid" role="region" tabindex="0" aria-label="Shipment records">
    <table>
      <caption class="forma-visually-hidden">Shipment records</caption>
      <thead>
        <tr>
          <th scope="col" aria-sort="ascending"><button type="button">Shipment</button></th>
          <th scope="col"><button type="button">Consignee</button></th>
          <th scope="col"><button type="button">Origin</button></th>
          <th scope="col"><button type="button">Destination</button></th>
          <th scope="col"><button type="button">Weight</button></th>
          <th scope="col"><button type="button">Status</button></th>
          <th scope="col"><span class="forma-visually-hidden">Actions</span></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td data-label="Shipment"><span class="forma-identifier">SHP-2026-000418</span></td>
          <td data-label="Consignee">Rheinland Präzisionswerkzeuge und Industriebedarf GmbH</td>
          <td data-label="Origin">Rotterdam, NL</td>
          <td data-label="Destination">Duisburg, DE</td>
          <td data-label="Weight">12,480 kg</td>
          <td data-label="Status"><span class="forma-status-lozenge" data-state="ok">Delivered</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open SHP-2026-000418">Open</button></td>
        </tr>
        <tr>
          <td data-label="Shipment"><span class="forma-identifier">SHP-2026-000419</span></td>
          <td data-label="Consignee">Coastal Grain Cooperative</td>
          <td data-label="Origin">Antwerp, BE</td>
          <td data-label="Destination">Lyon, FR</td>
          <td data-label="Weight">—</td>
          <td data-label="Status"><span class="forma-status-lozenge" data-state="blocked">Held at customs</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open SHP-2026-000419">Open</button></td>
        </tr>
      </tbody>
    </table>
  </div>
</forma-data-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 record projection

At phone width the header row disappears and each row becomes a bordered record whose cells print their data-label. The row action stretches to the full record width.

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.

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 the table, rows and cells switch to block display; thead is hidden and every td shows its data-label in a 6.5rem label column beside the value.
  • The region drops its border and horizontal scrolling; each record gets its own border and bottom margin instead, so nothing scrolls sideways at 320px.
  • Children of the td[data-label="Actions"] cell stretch to 100% width, giving a full-width touch target per record.
  • Header sort buttons are hidden with thead, so sorting is not reachable on phones from the grid itself. Offer sort in a Collection toolbar or equivalent control.
  • Rotating to landscape above 30rem restores the table layout inside the scrolling region.
HTML · Mobile record projection Raw HTML for HTML · Mobile record projection
<forma-data-grid class="forma-component-tag">
  <div class="forma-data-grid" role="region" tabindex="0" aria-label="Open support tickets">
    <table>
      <caption class="forma-visually-hidden">Open support tickets</caption>
      <thead>
        <tr>
          <th scope="col" aria-sort="ascending"><button type="button">Ticket</button></th>
          <th scope="col"><button type="button">Subject</button></th>
          <th scope="col"><button type="button">Status</button></th>
          <th scope="col"><span class="forma-visually-hidden">Actions</span></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td data-label="Ticket">SUP-3120</td>
          <td data-label="Subject">Cannot export the quarterly usage report as CSV</td>
          <td data-label="Status"><span class="forma-status-lozenge" data-state="attention">Awaiting reply</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open SUP-3120">Open</button></td>
        </tr>
        <tr>
          <td data-label="Ticket">SUP-3124</td>
          <td data-label="Subject">Single sign-on loop after password change</td>
          <td data-label="Status"><span class="forma-status-lozenge">New</span></td>
          <td data-label="Actions"><button type="button" aria-label="Open SUP-3124">Open</button></td>
        </tr>
      </tbody>
    </table>
  </div>
</forma-data-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.

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.

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-data-gridregion—Makes the scroll container a named landmark so keyboard and screen-reader users can find and scroll it.
tabindex.forma-data-grid0—Lets keyboard users focus the region and scroll overflowing columns with the arrow keys.
aria-label.forma-data-gridstring—Names the region. Use a distinct name per grid on the page.
scopethcol—Associates each header with its column on wide layouts.
aria-sortthascending | descendingabsent (unsorted)Written by the application on the one sorted column. Forma appends ↑ or ↓ to the header button from this value.
data-labeltdcolumn name—Required on every cell. Printed as the cell's label at 30rem and below, when the header row is hidden. Actions also stretches the cell's children to full width.
typebuttonbutton—Header sort buttons and row actions are native buttons; type="button" prevents accidental form submission.
aria-labelrow action buttonstring—Names the record a repeated action applies to, such as "Open INV-1042".
datetimetimeISO date—Machine-readable date for date cells; the visible text stays human-formatted.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-data-gridBlock class—Root scroll region around the native table. Bordered, horizontally scrollable, and recomposed into labelled records at 30rem and below.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the region, the header sort buttons and row actions in document order.
Arrow keysScroll the focused region horizontally and vertically (native scrolling). There is no cell-by-cell navigation.
Enter / SpaceActivate a focused sort button or row action. What sorting does is application behavior.
Events
EventDescription
clickNative click on header and row buttons. The application sorts or navigates, then re-renders rows and moves aria-sort.

Form behavior

Not a form control. Row selection checkboxes or inline inputs, if added, participate in their own form as ordinary native controls.

States

Data grid states
StateHow it is expressedPresentation
Unsortedno aria-sort on any thHeader buttons show their label only.
Sorted ascendingaria-sort="ascending" on thThe header button shows an up arrow after its label; assistive technology announces the sort.
Sorted descendingaria-sort="descending" on thThe header button shows a down arrow after its label.
Overflowingtable wider than the regionThe region scrolls horizontally inside its border because the table keeps a 42rem minimum width.
Record projectionviewport ≤ 30remHeader hidden; rows are bordered records; cells show their data-label.
Emptyempty tbody plus an application-rendered Empty stateForma has no built-in empty row; the application explains the absence of records.

Accessibility

Forma provides

  • Keeps a native table with th scope, so row and column relationships come from the platform on wide layouts.
  • Derives the sort arrow from aria-sort, so the visible indicator cannot disagree with what assistive technology announces.
  • Header sort buttons keep a 2.25rem minimum height; row actions stretch to full width on phones.
  • In the phone projection each value is preceded by its visible column label from data-label, replacing the hidden header.

Your application supplies

  • Provide a caption (it may be visually hidden) and a unique aria-label on the region.
  • Put data-label on every td, matching the column header text.
  • Move aria-sort to the sorted column and announce sort or result changes in a live region such as the Collection toolbar count.
  • Give repeated row actions record-specific accessible names.
  • Express status as text; do not rely on row or cell color.
  • If the grid needs cell navigation, selection or editing, implement the ARIA grid keyboard model in Limen/application code.

Responsive behavior

  • Above 30rem the table keeps a 42rem minimum inline size and the .forma-data-grid region scrolls horizontally, so the page never overflows.
  • At 30rem and below the grid recomposes into stacked records: thead hidden, every cell a minmax(6.5rem, 0.4fr) minmax(0, 1fr) label/value grid.
  • Long text wraps inside cells; identifiers can use Identifier & critical value so long codes break safely.
  • The application decides which columns are essential. For very wide data on phones, prefer fewer columns or a detail view over many labelled lines per record.
  • Sort controls disappear with the header on phones; supply an equivalent sort control outside the grid.

Motion

  • No animation: sorting, the sort arrow and the phone recomposition change instantly. Re-ordered rows are replaced by the application without transitions.

Usage guidance

Do

  • Keep the header label, data-label and any sort control wording identical.
  • Show the result count and active filters next to the grid so an empty or short table is explained.
  • Pair large result sets with Pagination or an application-owned loading strategy.

Avoid

  • Sorting in the browser with script that Forma does not know about, then forgetting to update aria-sort.
  • Using row color or position to signal priority, risk or status.
  • Putting several unrelated actions in each row; open a detail view or use a Action menu instead.

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.