Record Grid

Demo & usage

More examples

<!-- What this renders below the breakpoint: a list of records, each a
     real description list. Not a table pretending to be blocks. -->
<ul role="list">
  <li>
    <article aria-labelledby="...">
      <h3 id="...">Ada Lovelace</h3>
      <dl>
        <div><dt>Status</dt><dd>Shipped</dd></div>
        <div><dt>Total</dt><dd>£42.00</dd></div>
      </dl>
    </article>
  </li>
</ul>

readonly columns: TableColumn[] = [
  { key: 'customer', label: 'Customer' },
  { key: 'total', label: 'Total', sortable: true },
  { key: 'reference', label: 'Reference', priority: 'secondary' },
  { key: 'channel', label: 'Channel', priority: 'secondary' },
];

<sv-record-grid [columns]="columns" [rows]="sortedRows()" [(sort)]="sort" [(selected)]="picked" />

// The host owns the order — the grid reports the choice, it does not sort.
readonly sortedRows = computed(() => {
  const s = this.sort();
  if (!s?.direction) return this.rows();
  const dir = s.direction === 'asc' ? 1 : -1;
  return [...this.rows()].sort((a, b) =>
    String(a[s.key]).localeCompare(String(b[s.key]), undefined, { numeric: true }) * dir);
});

<sv-record-grid [columns]="columns" [rows]="rows" mode="auto" [breakpoint]="900">
  <ng-template svRecordTable>
    <sv-data-table-pro [columns]="columns" [rows]="rows" (sortChange)="onSort($event)" />
  </ng-template>
</sv-record-grid>

When to use

• Any data table that has to work on a phone — which is most of them.
• A table embedded in a narrow panel on a wide screen: set mode="cards" directly, because a media query cannot see the panel.
• For a genuinely small set of fields per record, a Descriptions list on its own may be all you need.

Async states

• loading
• empty
• error
• retry

Item identity & owned state

Item key

rowKey — set this when your rows have no id, so selection survives a reorder.

Restorable state

• expandedIds
• selected

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Outputs

<sv-record-grid-pro>

Also in this family — SvRecordGridProComponent from @styloviz-pro/data-table.

Inputs

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

<sv-record-grid
  [rows]="data.items()"
  [loading]="data.loading()"
  [error]="data.error()"
  (retry)="data.reload()"
/>

// This component reports its state but does not emit a query, so drive
// it from your own fetch and bind the three async inputs.
readonly items = signal<Row[]>([]);
readonly loading = signal(false);
readonly error = signal<SvDataError | null>(null);

async load(): Promise<void> {
  this.loading.set(true);
  this.error.set(null);
  try {
    this.items.set(await this.api.fetchRows());
  } catch (e) {
    this.error.set(toSvDataError(e));
  } finally {
    this.loading.set(false);
  }
}

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `rows`, `loading` and `error`.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• `mode` (`auto` / `table` / `cards`) and `breakpoint` decide which view is on screen; `auto` measures the viewport with `matchMedia`, and re-measures when `breakpoint` changes.
• `titleKey` promotes one field to the card heading; `priority: 'secondary'` on a column moves it behind the per-card disclosure.
• `selectable` + two-way `selected`, two-way `sort` (the host sorts `rows` from it), and `rowActions` carry the table's contracts into the card view.
• Two-way `expandedIds` holds which cards have their secondary fields open, keyed by `rowKey`, so a host can restore it.
• Full async contract: `loading`, `error`, `emptyMessage` and a `retry` output, in either view.
• Ships in both tiers: `sv-record-grid` from `@styloviz/data-table` and `sv-record-grid-pro` from `@styloviz-pro/data-table`.

Best practices

• Do: Set `titleKey` to the field a reader would use to identify the record. A `<dl>` cannot supply a heading — every pair in it is equally a term — so one field is promoted out, and the default (the first column) is rarely the best one.
• Do: Mark the fields that matter least as `priority: 'secondary'` rather than removing them from `columns`. They move behind a disclosure that says how many are in it.
• Do: Bind `sort` and `selected` two-way, and sort the rows you bind from `sort` — the host sorts rows from sort; the grid only reports the choice. Keep the table's sort on the same state and switching views never loses the order or the selection.
• Do: Set `rowKey`. Tracking by position reuses one record's DOM for another on the next sort or page, so a checkbox stays ticked while the record under it changes.
• Don't: Don't reach for the `display: block` CSS trick instead. It drops the table roles and replaces selectable text with generated content — it looks like this and is less accessible than the table it replaced.
• Don't: Don't pass the wide view as projected content. Use the `svRecordTable` template, or every record ends up in the accessibility tree twice.

Accessibility

• Keyboard at scale (X-10): the grid renders every record it is given — paging is the host's. Documented ceiling: 2,000 records, past which a dev-mode warning fires; pair it with `sv-pagination` above that.
• Below the breakpoint the markup **stops claiming to be a table**. It is a `<ul role="list">` of `<article>` cards, each labelled by its own heading and holding a real `<dl>` of `<dt>`/`<dd>` pairs — which is what a screen reader announces as "Status, definition, Shipped".
• The labels are real text, not `::before` generated content, so they can be selected, searched and copied.
• Every control names the record it acts on — "Select Grace Hopper", "Refund Grace Hopper", "Show 2 more fields for Ada Lovelace" — because a card list has no row context to fall back on.
• The sort control is a labelled `<select>` with a named direction button rather than an icon, since the header cell that used to carry the affordance is gone.
• A server render shows the table, because a prerender cannot measure and the table is the view that holds every field and every label.