Data grid

When to use it

Use it when the reader operates on data rather than reading it: sorting, selecting rows, scanning a hundred records for one. For data you present rather than manipulate, .table is lighter and does not need JavaScript.

.dg-wrap is not optional — it carries the scroll container, the height cap, the border and the custom properties every other rule reads. The <table> goes inside it.

<div class="dg-wrap">
  <table class="dg">
    <thead><tr>
      <th scope="col">Invoice</th>
      <th scope="col">Client</th>
      <th scope="col">Status</th>
      <th scope="col" class="dg-num">Amount</th>
    </tr></thead>
    <tbody>
      <tr>
        <th scope="row">INV-2291</th>
        <td>Ada Chen</td>
        <td>Paid</td>
        <td class="dg-num">1,240.00</td>
      </tr>
      <tr>
        <th scope="row">INV-2292</th>
        <td>Marco Silva</td>
        <td>Pending</td>
        <td class="dg-num">86.50</td>
      </tr>
      <tr>
        <th scope="row">INV-2293</th>
        <td>Priya Raman</td>
        <td>Overdue</td>
        <td class="dg-num">12,900.00</td>
      </tr>
    </tbody>
  </table>
</div>

Frozen header and pinned columns

The header is position: sticky with inset-block-start: 0. Pinned columns are sticky on the inline axis, and the two combine: a pinned header cell needs a higher z-index than a pinned body cell, which is why the source has four z-index rules rather than one.

Put the class on every cell in the column, header included. A second pinned column needs to know how wide the first one is, and that is --dg-pin-start — measured by deck.js with a ResizeObserver, so it stays correct when the column is resized or the font changes.

@supports (container-type: scroll-state) {
  .dg-wrap { container-type: scroll-state; }
  @container scroll-state(scrollable: inline-start) {
    .dg :is(th, td).dg-pin-start:last-of-type { box-shadow: var(--dg-pin-shadow-start); }
  }
}

Sorting

Put data-sort="num", "text" or "date" on a header cell and data-deck-grid on the wrapper. deck.js replaces the header's text with a real <button class="dg-sort"> and sorts on click, setting aria-sort on the <th>.

The styling keys off that attribute — th[aria-sort] .dg-sort { color: var(--brand) } and a rotate: 180deg for descending — so the arrow direction and the announced sort state are the same value. There is no separate .is-sorted class to fall out of step.

<div class="dg-wrap" data-deck-grid>
  <table class="dg">
    <thead><tr>
      <th scope="col" data-sort="text">Client</th>
      <th scope="col" class="dg-num" data-sort="num">Amount</th>
    </tr></thead>
    …
  </table>
</div>

Sorting is client-side and re-orders the rows in the DOM. For a grid backed by a paged API that is wrong — it sorts the page rather than the data — so leave data-sort off and sort on the server, keeping aria-sort on the header yourself so the styling still works.

Density

--dg-row-h drives the row height, and two classes set it: .dg-compact at 34px with smaller text, .dg-comfy at 56px. The default is 44px, which is the touch target.

<div class="dg-wrap">
  <table class="dg dg-compact">
    <thead><tr>
      <th scope="col">Invoice</th>
      <th scope="col">Client</th>
      <th scope="col">Status</th>
      <th scope="col" class="dg-num">Amount</th>
    </tr></thead>
    <tbody>
      <tr>
        <th scope="row">INV-2291</th>
        <td>Ada Chen</td>
        <td>Paid</td>
        <td class="dg-num">1,240.00</td>
      </tr>
      <tr>
        <th scope="row">INV-2292</th>
        <td>Marco Silva</td>
        <td>Pending</td>
        <td class="dg-num">86.50</td>
      </tr>
      <tr>
        <th scope="row">INV-2293</th>
        <td>Priya Raman</td>
        <td>Overdue</td>
        <td class="dg-num">12,900.00</td>
      </tr>
    </tbody>
  </table>
</div>

Cell variants are independent of density: .dg-num aligns to the end edge, .dg-center centres, .dg-tight narrows the padding, .dg-wrap-text allows wrapping with a 16rem floor, and .dg-actions shrinks a column to its content. Everything else is white-space: nowrap, which is what keeps columns aligned while the grid scrolls.

Selection

Row selection is tr[aria-selected="true"] — again the accessible state doing the styling. .dg-check is the 44px checkbox column, and it is the one place Deck deliberately strips .check's min-block-size: a dense grid of 34px rows cannot also have 44px checkboxes.

.dg-selection is the bar that appears when rows are selected, and .dg-statusbar the row-count footer.

<div class="dg-wrap">
  <table class="dg">
    <thead><tr>
      <th scope="col" class="dg-check"><label class="check"><input type="checkbox"><span class="sr-only">Select all</span></label></th>
      <th scope="col">Invoice</th>
      <th scope="col" class="dg-num">Amount</th>
    </tr></thead>
    <tbody>
      <tr aria-selected="true">
        <td class="dg-check"><label class="check"><input type="checkbox" checked><span class="sr-only">Select INV-2291</span></label></td>
        <th scope="row">INV-2291</th><td class="dg-num">1,240.00</td>
      </tr>
      <tr>
        <td class="dg-check"><label class="check"><input type="checkbox"><span class="sr-only">Select INV-2292</span></label></td>
        <th scope="row">INV-2292</th><td class="dg-num">86.50</td>
      </tr>
    </tbody>
  </table>
</div>

Cards on a phone

.dg-cards restacks each row into a labelled card below a breakpoint, reading the column name from data-label on each cell — the same technique as .table-stack, and it carries the same cost: the columns stop being comparable.

.dg-cq does it on the container's width instead, which is the version to prefer. A grid in a split rail on a wide monitor is in a narrow space, and a viewport media query gets that wrong.

<div class="dg-wrap dg-cards-wrap">
  <table class="dg dg-cards">
    <thead><tr>
      <th scope="col">Invoice</th>
      <th scope="col">Client</th>
      <th scope="col">Status</th>
      <th scope="col" class="dg-num">Amount</th>
    </tr></thead>
    <tbody>
      <tr>
        <th scope="row" data-label="Invoice">INV-2291</th>
        <td data-label="Client">Ada Chen</td>
        <td data-label="Status">Paid</td>
        <td class="dg-num" data-label="Amount">1,240.00</td>
      </tr>
      <tr>
        <th scope="row" data-label="Invoice">INV-2292</th>
        <td data-label="Client">Marco Silva</td>
        <td data-label="Status">Pending</td>
        <td class="dg-num" data-label="Amount">86.50</td>
      </tr>
      <tr>
        <th scope="row" data-label="Invoice">INV-2293</th>
        <td data-label="Client">Priya Raman</td>
        <td data-label="Status">Overdue</td>
        <td class="dg-num" data-label="Amount">12,900.00</td>
      </tr>
    </tbody>
  </table>
</div>

Long grids

.dg-virtual puts content-visibility: auto on every row, with contain-intrinsic-size matched per density — 34px for .dg-compact, 56px for .dg-comfy. The browser skips layout and paint for offscreen rows, and the scrollbar stays honest because the placeholder height is right.

That per-density pairing is the detail .list-virtual does not have: the list assumes 56px whatever its rows actually are. Here the two density classes each declare their own intrinsic size, so the estimate is never wrong by design.

Loading, empty and new

.is-loading on the wrapper dims the body, disables pointer events and runs an indeterminate bar across the top. .dg-empty is the row that holds an empty state. .is-new flashes a row green for 1.4 seconds when it arrives — useful for a live-updating grid, and easy to overuse.

All five is- states here are set by deck.js at runtime and are internal. .is-scrolled-x and .is-scrolled-end only exist at all as a fallback for browsers without scroll-state queries.

Classes

Generated from the stylesheet source by tools/docs/extract.mjs.

Tokens

Four local properties on .dg-wrap shape the grid: --dg-row-h, --dg-height, --dg-pin-start and --dg-pin-end. The rest are global.

Accessibility

• It is a real table, so the semantics are free. Header association, row and column navigation, and the row count all come from the element. Every header still needs scope, and the first cell of each row should be a <th scope="row">.
• Sorting is announced through aria-sort, which is also what styles the arrow. The sort control is a real <button> inside the header, generated by deck.js — so it is focusable and operable without a mouse.
• Selection is announced through aria-selected on the row. The checkbox still needs its own accessible name — the examples here use .sr-only text, because a bare checkbox in a grid is announced as "checkbox" with no indication of which row.
• The checkbox column is under the touch target. .dg-check .check drops min-block-size, so the target is the row height — 34px in compact mode. This is a deliberate density trade and one of four such places in Deck.
• The scroll container needs a tab stop. .dg-wrap is overflow: auto and sets no tabindex, so a keyboard user cannot scroll it horizontally unless a cell in the off-screen region is focusable. Add tabindex="0" and role="region" with a label. Same defect as .table-wrap.
• Column resizing is pointer-only. .dg-resize is a drag handle with no keyboard equivalent. Column widths are a preference rather than content, so nothing is unreachable — but a keyboard user cannot adjust them.
• The loading bar is decoration. .is-loading dims the body and animates a bar; nothing is announced. Put the state in an aria-live region, or the grid silently goes quiet for a screen-reader user.
• .is-new is colour-only and lasts 1.4 seconds. A row arriving is not announced either. For a live grid, an aria-live="polite" summary — "3 new rows" — carries far more than the flash does.
• Card mode keeps the header in the tree. Like .table-stack, the <thead> is clipped rather than removed, so header association survives the restack.

Right to left

Pinning uses inset-inline-start and inset-inline-end, cells use text-align: start, and the scroll-state queries use scrollable: inline-start — all logical, all mirrored for free.

Two things are not. A box-shadow offset is physical, and so is a clip-path inset; both live in custom properties on .dg-wrap so src/19-logical.css can mirror the geometry in one place rather than in each of the four branches that use it.

Grid.shadows() also takes Math.abs(scrollLeft), because an RTL scroller counts down from zero. That single abs is what makes the JavaScript fallback work in both directions.

<div dir="rtl">
<div class="dg-wrap">
  <table class="dg">
    <thead><tr>
      <th scope="col">Invoice</th>
      <th scope="col">Client</th>
      <th scope="col">Status</th>
      <th scope="col" class="dg-num">Amount</th>
    </tr></thead>
    <tbody>
      <tr>
        <th scope="row">INV-2291</th>
        <td>Ada Chen</td>
        <td>Paid</td>
        <td class="dg-num">1,240.00</td>
      </tr>
      <tr>
        <th scope="row">INV-2292</th>
        <td>Marco Silva</td>
        <td>Pending</td>
        <td class="dg-num">86.50</td>
      </tr>
      <tr>
        <th scope="row">INV-2293</th>
        <td>Priya Raman</td>
        <td>Overdue</td>
        <td class="dg-num">12,900.00</td>
      </tr>
    </tbody>
  </table>
</div>
</div>

Reduced motion

Two animations: the .is-new row flash and the .is-loading bar. Under prefers-reduced-motion: reduce the global reset collapses animations to a single .01ms iteration — but the loading bar is in the reset's exemption list alongside spinners and skeletons, so it keeps moving at 2.4 seconds rather than freezing.

That is the right call: a frozen progress indicator reads as a hung page, which is worse for everyone than a slow one.

Printing

Sixteen rules, the most of any component. The grid becomes a plain table: display: table-header-group on the <thead> so the header repeats on every page, break-inside: avoid on rows, font-size: 9.5pt, and the card mode fully unwound — display: table, table-row, table-cell, with the ::before labels set to content: none.

.dg-toolbar and .dg-resize are in the never-print list, and the header keeps its grey fill through print-color-adjust: exact.

Overriding it

/* One grid, no layer needed */
<div class="dg-wrap" style="--dg-height:40dvh;--dg-row-h:38px">

@layer app.components {
  /* A third pinned column */
  .dg :is(th, td).dg-pin-start-3 {
    position: sticky;
    inset-inline-start: calc(var(--dg-pin-start) + var(--dg-pin-start-2, 0px));
    z-index: 2;
  }

  /* A focus background for keyboard users */
  .dg tbody tr:focus-within td { background: var(--surface-hover); }
}

A third pinned column needs its own offset property measured the way --dg-pin-start is; Deck ships two because two is where the pattern stops being worth the complexity.

When not to use it

• Not for data you only present. Use .table. The grid brings a scroll container, a height cap, six files of CSS and a JavaScript class for behaviour you are not using.
• Not for a list of one-line items. Use .list, which has row semantics and touch targets without the column machinery.
• Not with client-side sorting over a paged API. It sorts the visible page and looks like it sorted the data. Sort on the server and set aria-sort yourself.
• Not with more than two pinned columns. Each one needs a measured offset, and past two the pinned region is most of a phone's screen.
• Not as a spreadsheet. There is no cell editing, no keyboard grid navigation and no formula layer. role="grid" would promise all three; Deck's is a table, and it is announced as one.