Data List

Install

pnpm dlx shadcn@latest add @vegastack/data-list

Usage

import { DataList, type DataListColumn } from "@/components/ui/data-list";

interface User {
  id: string;
  name: string;
  role: string;
}

const columns: DataListColumn<User>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "role", header: "Role" },
];

<DataList columns={columns} data={users} getRowId={(u) => u.id} />;

DataList<T> is generic over the row type, so render, getRowId, and the selection/sort callbacks are all fully typed against your data.

Anatomy

DataList is a single generic component composed on top of the design-system primitives — it renders a Table using the shared data-table-parts: the sort header, the selection cells, the skeleton rows, the empty row and the column class rules it has in common with DataGrid.

<DataList<T>
  columns={[
    { key, header, render?, sortable?, align?, mono?, nowrap?, className?, headerClassName?, interactive? },
  ]}
  data={rows}
  getRowId={(row, index) => string}
  selectable
  selectedIds={selected}            // controlled selection (Set<string>)
  onSelectionChange={setSelected}
  sort={sort}                       // controlled sort ({ key, direction } | null)
  onSortChange={setSort}
  loading={false}
  emptyState={/* optional override */}
/>;

• Root — a <table data-slot="data-list"> inside the shared scroll viewport, which takes a tab stop (and its aria-label) only while the table can actually scroll.
• Selection column — when selectable, a leading checkbox column with a tri-state select-all in the header (data-slot="checkbox"); each body row carries data-selected when picked.
• Sortable header — sortable columns render a ghost Button (data-slot="data-table-sort") inside <th data-slot="data-list-head">, which carries aria-sort on every sortable column ("none" included) and data-sorted="asc|desc"; clicking cycles asc → desc → cleared.
• Body — one <tr data-slot="data-list-row"> per row; cells use column.render or fall back to row[column.key], and wrap by default (see Wrapping below).
• Loading — skeleton rows (data-slot="data-list-skeleton-row") replace the body while loading; the table gets aria-busy and a live status while placeholder rows stay aria-hidden.
• Empty — a single full-width row (data-slot="data-list-empty-row") hosting the emptyState.

Examples

Selection

Pass selectable to add the checkbox column. Selection is controllable — lift it with selectedIds + onSelectionChange, or omit both for built-in uncontrolled state. The header checkbox is indeterminate when only some rows are selected, checked when all are, and toggles every row on click.

Sorting

Mark a column sortable to make its header interactive. Sorting is controlled by intent: onSortChange fires with the next { key, direction } (or null when cleared) and you re-order data — the same API works for client-side and server-side sorting. The header reflects the active sort with an arrow icon, aria-sort, and data-sorted.

const [sort, setSort] = React.useState<SortState | null>(null);

<DataList
  columns={columns}
  data={sortRows(rows, sort)} // your comparator
  getRowId={(r) => r.id}
  sort={sort}
  onSortChange={setSort}
/>;

Row activation

Pass onRowClick to make rows activatable — for navigating to a detail page, opening a drawer, and so on. DataList stays presentational: it only signals the activation; the host decides what it does.

<DataList
  columns={columns}
  data={rows}
  getRowId={(r) => r.id}
  onRowClick={(row) => router.push(`/people/${row.id}`)}
/>

Activation accessibility

Activatable rows are built to preserve native table semantics. The <tr> is not given role="button" / tabIndex — overriding the implicit role="row" would make its <td>/<th> children invalid cells for assistive tech and break row/column navigation. Instead:

• The <tr> keeps role="row" and gets a mouse-only onClick (a <tr> may carry onClick with no role — that's valid) plus data-clickable for styling.
• A real <button data-slot="data-list-row-action"> is injected into the first cell as the keyboard / screen-reader activation control — it is focusable and fires on Enter / Space, with a :focus-visible ring, all inside a valid <td>.
• Clicks on the selection checkbox, the injected button, or any nested control are excluded from the row's onClick, so there's no double-activation.

If the first column already renders its own interactive control (a link or button), set column.interactive on it so DataList skips the injected button (it never nests one interactive element inside another) — keyboard activation then comes from your in-cell control.

const columns: DataListColumn<Person>[] = [
  {
    key: "name",
    header: "Name",
    interactive: true, // first column owns its focusable control → skip injected button
    render: (p) => <a href={`/people/${p.id}`}>{p.name}</a>,
  },
  // …
];

<DataList
  columns={columns}
  data={rows}
  getRowId={(p) => p.id}
  onRowClick={open}
/>;

Loading & Empty states

loading swaps the body for loadingRows skeleton rows (default 5). When data is empty and not loading, DataList renders a built-in Empty — override it with the emptyState prop.

Pass emptyState to fully replace the built-in node — for a filtered "no results" message with its own icon and actions, for example:

Scope

DataList is the presentational data table — columns, render functions, row selection, sortable-header signalling, loading, and empty state. It deliberately does not own data-fetching or app-coupled data management. To make host composition ergonomic it exposes presentational slots + callbacks (no app logic of its own): a toolbar slot (above the table), a footer slot (below it), and onRowClick (activatable, keyboard-accessible rows). The host drops its own search/filter and pagination controls into the slots and passes the already-filtered / already-paged rows:

// Host composes search + paging around the primitive
<DataList
  columns={columns}
  data={pageRows} // already filtered + paged by the host
  toolbar={<SearchInput value={q} onValueChange={setQ} />}
  footer={<Pagination page={page} onPageChange={setPage} />}
  onRowClick={(row) => router.push(`/items/${row.id}`)}
/>

Here the host owns a search box (in toolbar) and a pager (in footer), filtering and paging the data itself — DataList only renders the already-filtered, already-paged rows and the two slots:

This split mirrors the design system's G7 presentational/app-coupled rule — the primitive stays presentational and reusable; the app wires the data and view state. Full platform parity — grouping, inline editing, multi-key sort, column management, virtualization — is DataGrid, and the Kanban tier is Board; this primitive stays the presentational default.

API Reference

Column

column.render is invoked as a plain function inside DataList's own render, not mounted as a component — so hooks called directly in its body become DataList's hooks and corrupt hook order the moment the loading or empty branch flips. When a cell needs hooks, return a component element and put the hooks in that component:

// ✅ hooks live in RelativeCell, mounted as an element
{ key: "updated", header: "Updated", render: (row) => <RelativeCell date={row.updatedAt} /> }

// ❌ a hook called directly here corrupts DataList's hook order
{ key: "updated", header: "Updated", render: (row) => useRelative(row.updatedAt) }

render also receives an optional third argument, DataListCellContext — { rowId, columnKey, selected } — so a cell can react to its own row's selection without threading state through the row type. Existing two-argument render functions keep working unchanged.

Wrapping and the mono face

Cells wrap by default (D18): a long value breaks inside its own column instead of forcing the whole table to scroll. Two column shapes are unreadable when broken, so they opt back out automatically:

• align: "end" — the numeric convention.
• mono: true — renders values in the mono numeral face (font-mono text-code tabular-nums) so figures line up down the column, and pins them to one line.

nowrap overrides the inference in either direction: nowrap: true pins a prose column, and nowrap: false lets an end-aligned column wrap. The floor a wrapping column may shrink to is --table-cell-min-width on the underlying Table.

const columns: DataListColumn<Invoice>[] = [
  { key: "ref", header: "Ref", mono: true }, // one line, mono numerals
  { key: "subject", header: "Subject" }, // wraps
  { key: "amount", header: "Amount", align: "end" }, // one line
  { key: "note", header: "Note", align: "end", nowrap: false }, // end-aligned but wrapping
];

Sort types

SortDirection is a string-union alias and SortState is the small object you pass to sort / receive from onSortChange, so they are documented as hand-written tables:

SortDirection is "asc" | "desc". onSortChange receives SortState | null — null means the sort was cleared (the third click on a header).

Accessibility

• Renders a real semantic <table> with <thead>/<tbody> and <th> header cells, so screen readers announce row/column structure natively.
• Sortable headers expose aria-sort (ascending / descending / none) and are real <button>s — keyboard Enter / Space activate them, with a :focus-visible ring.
• The select-all and per-row checkboxes have explicit aria-labels (e.g. Select all rows, Select row 1) and are fully keyboard operable.
• While loading, the table has aria-busy="true" and is described by a polite role="status" node. Skeleton rows are decorative (aria-hidden); the empty state carries its meaning in the title/description text, never by icon or color alone.
• Activatable rows (onRowClick) keep native table semantics: the <tr> is never given role="button"/tabIndex (which would invalidate its cells). A real <button> injected into the first cell is the focusable keyboard / screen-reader activation; the row's onClick is mouse-only convenience.

Do / Don't