Data List

Install

pnpm exec vegastack-design verify data-list

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

Usage

Default grid cards also support callback-only onRowClick activation with Enter and Space. Nested selection and action controls keep their own behavior.

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.

In a ListToolbar. Pass a ListToolbar as toolbar and DataList fills it: views with onViewChange become its Layout tool (icon buttons), and onDensityChange becomes Display's Row height (a DisplayMenu is added when the toolbar has none). A toolbar that sets its own layout or row height keeps them. An empty list keeps its toolbar but drops the column header; noResults takes onEditFilters for an "Edit filters" button beside "Clear filters". While rows are selected the list keeps a spacer the bulk bar's height, so the last row is never covered.

Anatomy

DataList is a single generic component composed on top of the design-system primitives — it renders a Table using the shared @vegastack/data-table-parts (a shared internal, installed with this component): 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?, numeric?, nowrap?, minWidth?, mobile?, 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}
  empty={{ title: "No tasks yet" }}
/>;

• Root — one <div data-slot="data-list-root"> stack in every configuration, holding the optional toolbar, the table, the status lines and the optional footer, so nothing DataList adds lands as a stray child of your own layout. ref, className and every <table> attribute go to the <table data-slot="data-list"> inside it, which sits in the shared scroll viewport.
• 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. Its label wears the plain header's own text-sm font-medium in text-foreground, so sortable and static headers read as one row.
• 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). A selected row keeps a light bg-muted/50 wash through hover and press — light enough that a secondary Badge inside it stays visible (the full accent is the badge's own fill).
• 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 empty state (empty, or your emptyState).
• Merged stack — when the container is too narrow, overflow columns render inside the first cell as <span data-slot="data-list-merged">, the sorted one marked data-sorted.
• Status lines — under the table, in <div data-slot="data-list-status">: a column dropped with mobile: "hidden" is counted in <p data-slot="data-list-hidden-hint">, and a sort whose column is merged or hidden is stated in <p data-slot="data-list-sort-hint"> (see Fitting the width).

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.

Range and keyboard selection

Shift-click a checkbox to select — or clear — everything between it and the last checkbox toggled, in the order the rows read (a collapsed section's rows are stepped over). With focus anywhere in the list, ⌘/Ctrl+A selects every row, Esc clears the selection, and Space on a focused row link toggles that row. None of them fire from a text field (a toolbar search keeps its own select-all) or from a row's ⋯ menu, and a

⌘/Ctrl-click on a row still opens its link in a new tab.

Selection bar

selectionActions docks an ActionBar at the bottom of the screen, centred over the list, while anything is selected: the count (selectionLabel), your actions — compose ActionBarButton — then any selectionSecondaryActions, and last a "Clear selection" button. Your render gets the selected ids and a clear() to call after a bulk action. On a phone the bar is capped at the screen width and its actions scroll sideways inside it. While the bar is open the list ends with a spacer of the bar's height, its gap and --dock-inset-bottom (a global audio player under it), so the last row and the loading tail stay reachable above both.

Grid selection

The grid view carries the same checkbox on each card, above the card's link: shown on hover or focus, always on a touch screen, and on every card once anything is selected. A selected card keeps the list's selected wash. Ranges and the keyboard work the same way.

Drag into folders

Set onDropInto and rows (list) or cards (grid) can be dragged onto drop targets: rows canDropOnRow accepts (folders), and any BreadcrumbDropTarget naming the same dragScope. Dragging a selected row carries the whole selection, and its drag image reads "3 items" (dragItemsLabel). canDropInto refuses a move — a folder into itself or its own descendant — and a refused target shows data-drop-invalid in the destructive tint; an accepted one washes in the primary tint (data-drop-over). A list row takes the drop in its middle half only — its top and bottom quarters never nest, so a drag aimed between two rows cannot land inside one — while a grid card takes it anywhere. onDropInto receives { ids, targetId } and may return a promise. Drag is pointer only: keep a "Move…" row action as the keyboard and touch path.

canMoveItem(row) locks single rows — a view-only record (here "Budget.xlsx"). A row it answers false for is no drag source and carries data-move-locked; a dragged selection leaves it behind, and it still opens and can still take drops. On the board view it is the Board's own canMoveItem: a locked card that neither drags nor lifts with Space.

Files dragged in from the desktop drop onto the same folder rows and cards with onDropFilesOnRow(rowId, entries): the row washes as for a move, dropped folders keep their structure in each entry's relativePath, and an outer useFileDrop surface (the canvas's own upload drop) leaves that drop alone — the innermost target wins. onFilesOverRow reports the row the files are over, and null when they leave, for naming the folder in your drop hint. Neither needs onDropInto.

Reorder by dragging

A hand-arranged order: set onReorderRow and list rows drag to a place between others. A drop on a row's top or bottom quarter lands the dragged rows before or after it — its top or bottom half when the row takes no drop inside — and a 2px seam in the drop-indicator blue (data-drop-edge="top" or "bottom") marks the place while the pointer is there. A folder row canDropOnRow accepts keeps its middle half for onDropInto, so one drag can either place or file. canReorderRow refuses a place — folders stay before files here — and a refused edge shows no seam. onReorderRow receives { ids, targetId, edge: "before" | "after" } and may return a promise. It is the list view's; a grid or board doesn't offer it. Drag is pointer only: keep Move up and Move down row actions as the keyboard and touch path.

Sorting

Mark any column sortable to make its header interactive; it carries aria-sort, data-sorted, and a button named Sort by <column>. onSortChange fires with the next { key, direction } (or null when cleared). The click cycle is the column's sortFirst (default "asc"; use "desc" for dates and amounts) → the other → none.

• Manual (default, sortMode="manual"): you re-order data — the right choice for server-side sorting.
• Client (sortMode="client", or any column with its own compare): DataList orders data itself with the column's compare(a, b) (ascending; descending is its reverse), else a default comparator over row[key] (numbers, dates, then numeric-aware strings, empties last).
• Read-only (sort without onSortChange): the sort is owned elsewhere, such as a toolbar's Sort control. No header is a button; the sorted column shows a read-only ↑/↓ (data-slot="data-table-sort-indicator") and carries aria-sort.

<DataList
  sortMode="client"
  columns={[
    { key: "name", header: "Name", sortable: true },
    {
      key: "due",
      header: "Due",
      sortable: true,
      sortFirst: "desc",
      compare: (a, b) => a.due.getTime() - b.due.getTime(),
    },
    {
      key: "priority",
      header: "Priority",
      sortable: true,
      compare: (a, b) => RANK[a.priority] - RANK[b.priority],
    }, // a custom order
  ]}
  data={rows}
/>

Manual, controlled:

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}
/>;

The indicator follows the standard sort-header pattern:

• Active column — its ↑ (ascending) or ↓ (descending) always shows, at foreground strength.
• Other sortable columns — the ⇅ is rendered but transparent, so the label never shifts; it fades in muted (text-muted-foreground) while the pointer hovers the header or the sort button has keyboard focus. Opacity only, no movement, and no fade under reduced motion.
• Touch — a coarse pointer never hovers, so only the active arrow shows; tapping a sortable header still sorts.
• Unsortable columns — no icon and no hover affordance.

Active ascending (Name, top) and active descending (Amount, bottom). Hover or tab to another sortable header — Role, say — to see the inactive indicator; Email and Status are not sortable:

Client sorting, live — click a header to cycle it:

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. A press anywhere on a grid card that is not one of its own controls (its checkbox, a menu, an interactive column) activates it.

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

Opening a record in place. onRowOpen(rowId, { event, index }) is the row-open contract a peek beside the list builds on, and wins over onRowClick. The whole row opens it — a plain click anywhere on it, or Enter on its first cell, in the list, the grid and the board. With getRowHref the row stays a real link: ⌘/Ctrl/Shift and middle clicks still open the full page where the browser would, and only a plain click (or Enter) is taken over. activeRowId marks the open row (data-peek-active, the accent wash, scrolled into view as it changes), and actionsRef.current.getRowOrder() returns the row ids in the order they read on screen — sections in order, a collapsed section's rows left out — so the peek's ↑/↓ walk the rows as shown.

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 the global 2px :focus-visible outline, 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}
/>;

Density

density sets the list's row height on one scale shared with DataGrid: comfortable rows are at least 40px, compact rows 32px. onDensityChange adds Row height to a ListToolbar toolbar's Display menu. Compact is one line per row. Merged values join the primary value's line instead of stacking under it (the line layout, whatever mergedLayout says), a plain primary value clamps to one line, and a thumbnail steps down to 24px. A custom render reads the density from its third argument (context.density) or, deeper down, useDataListDensity(); wrap a cell's second line in DataListSecondary and compact leaves it out.

render: (task) => (
  <div className="flex min-w-0 flex-col">
    <DataListSecondary className="text-xs text-muted-foreground">
      #{task.number} · {task.space}
    </DataListSecondary>
    <span className="truncate">{task.title}</span>
  </div>
);

Loading & Empty states

loading swaps the body for loadingRows skeleton rows (default 5). When data is empty and not loading, DataList renders one of two standard Empty states — never hand-roll empty markup:

• empty — there is nothing at all yet (no filters applied). The built-in Empty shows an Inbox icon and "Nothing here" in the table, the grid and every board lane. Pass only the copy the page needs — { icon, title, description, action } — for "No tasks yet" and a create action; a section's own empty wins for its lane. emptyState replaces the whole state with your own node (prefer empty). DataListEmptyState is the same state outside a DataList.
• noResults — the list is empty because of a search or filter. true shows the standard one: a SearchX icon, "No matches", a short description; pass { onClear } to add a "Clear filters" button wired to the FilterRow's onClear (title, description and clearLabel relabel it). NoResultsEmpty is the same state for a Board or a card grid.

<DataList
  columns={columns}
  data={rows}
  noResults={hasQueryOrFilters && { onClear: clearAll }}
  empty={{ icon: <ListTodo />, title: "No tasks yet" }}
/>

The noResults state, from a search with a Clear filters action:

Pass emptyState to fully replace the built-in node — for a filtered "no results" message with its own icon and actions, for example. The list's own empty state is the only empty state inside a list: pass empty (or emptyState) rather than putting a bordered Empty in or above the table, and give it one call to action. The empty row keeps an 8px inset (p-2), so a custom node never touches the header row above it.

Infinite loading (keyset)

A list fetched by cursor has no total and no page numbers. Pass loadMore and DataList loads the next cursor page as the list nears its scroll container's edge, through the shared LoadMore tail below the table (above footer): skeleton rows the height of real ones are appended to the table while the page loads, a failed page shows an error line with Try again, and — only when you pass endLabel — a caption once hasMore is false. There is no button. While hasMore is true the table reports aria-rowcount="-1", because the total is unknown.

loadMore.loading is a next-batch fetch; the list-level loading prop is the first-load skeleton.

<DataList
  columns={columns}
  data={rows}
  getRowId={(row) => row.id}
  loadMore={{
    hasMore: nextCursor != null,
    loading: isFetchingNextPage,
    error: fetchError ? "Couldn't load more people." : undefined,
    onLoadMore: fetchNextPage,
  }}
/>

Row actions

The standard: pass rowActions={(row) => RowAction[]} (with getRowLabel) and DataList adds the actions column itself — always the last column, with a 32px ghost ⋯ trigger per row (rowActionsLabel renames it). rowActionsColumn({ getRowLabel, actions }) is the same column for a host that assembles columns itself. Either way the column is one ⋯ menu per row, named for the row (Actions for Ada Lovelace). It is end-aligned, stays visible on narrow widths, and is interactive, so opening the menu never activates the row. Each menu mounts on demand — a row holds one plain button until its ⋯ is pointed at or pressed — so a long list pays for no menus up front. Each RowAction runs onSelect, or renders as a real link through render={<a href="…" />}; destructive paints it in the destructive ink; disabled keeps it in the menu — still reachable by the arrow keys — and disabledReason is a tooltip on the item and its accessible description (never wrapped text in the menu). The menu is at least 192px and as wide as its longest item, so labels never wrap; give items a leading muted icon (Pencil for Edit, Trash2 for Delete). A row with exactly one action that has an icon gets an icon button with a tooltip instead of a menu. The column header is Actions for assistive tech only. Put { type: "separator" } between groups — Copy link · Share ─ Copy summary ─ Delete — and leading, trailing or doubled separators are dropped, so a conditional group can leave one behind safely. The same entries drive the grid card's ⋯ and the board card's ⋯.

An action with items opens a submenu instead of running onSelect — Open · Copy link · Change status › · Assign › ─ Remove. Its entries are RowActions too, so separators, links, disabled reasons and destructive items work the same inside it.

Every item carries a leading icon (muted, per the icon rule) — Open (ArrowUpRight), Copy link (Link), Change status › (the current status's icon), Assign › (UserRoundPlus), Archive / Unarchive (Archive / ArchiveRestore), Cancel (CircleX, destructive). The menu is at least 12rem wide so no label wraps. A status submenu lists each status with its coloured StatusIcon, ticks the current one (checked) and shows its one-key shortcut (1–7 and 0) — pressing the key while the submenu is open picks it.

For a submenu that is more than a fixed list — Assign › with a searched, paged member list — pass submenu: a PanelSearch row, then a PanelList of DropdownMenuItems (it scrolls on its own, so the search stays at the top), each person drawn as a PersonOption — avatar, then name over email, stacked. Next to a submenu, items are the list's static actions — Assign to me, Unassign — and render in a PanelActions footer below the list, behind a hairline, as real menu items: give each an icon (UserCheck, UserMinus) and disabled when it would change nothing. The arrow keys reach them after the last person. A submenu popup is at least 18rem wide so a name and an email never truncate.

RowActionsMenu (and RowActionMenuItems, for a host that owns its own menu) are exported from data-table-parts; Board cards and SortableList rows use the same parts.

Rows as links

Row links and titles are never underlined, on hover or focus — the row's tint is the affordance.

getRowHref(row) makes each row a real link: the first cell's content becomes an <a> (or your router's link through rowLinkRender), so Enter, a middle click and ⌘/Ctrl/Shift-clicks are the browser's own. A click anywhere else on the row follows the same link with its modifiers; interactive cells (a checkbox, a menu) keep their own behaviour. A row without an href falls back to onRowClick. getRowLabel(row) names each selection checkbox ("Select Ada Lovelace").

highlightedIds (a Set of row ids) flashes those rows — the shortcut for rowProps's highlighted. rowProps(row, index) passes data-* attributes and a class through to each row, and highlighted flashes a row — one the user just created — in the accent wash, marked data-highlighted. Clear it after a moment; the list's own data-slot, data-selected and data-clickable always win over a passed attribute.

<DataList
  columns={columns}
  data={rows}
  getRowId={(r) => r.id}
  rowProps={(r) => ({ "data-id": r.id, highlighted: justAdded.has(r.id) })}
/>

Highlighted rows, through highlightedIds:

Sections

sections plus getRowSection split the rows into collapsible sections under the one header, in the order you list them: each non-empty section is its own <tbody> headed by a SectionRow — a th scope="rowgroup" with a disclosure button and the row count in muted tabular numerals (a section's count wins, for a server total); above 99 it shows "99+" and says the number through sectionCountLabel. Empty sections are omitted, rows in no listed section follow without a header, and select-all covers every loaded row. The collapsed state is groupState / defaultGroupState / onGroupStateChange, the same GroupState DataGrid's groups use.

Nested rows

getRowParentId nests a row under another, one level deep — a sub-task under its task. A row whose parent is loaded shows right after it, its title stepped in, and in the parent's section whatever its own; a row whose parent is not in data (filtered out, not loaded yet) stays where it is. The list owns the order and the folding, the host owns the toggle: a cell's render receives nesting (depth, children, expanded, setExpanded) in its context and puts the control where it reads best — a sub-task count, say. Fold state is collapsedParents / onCollapsedParentsChange (every parent starts expanded). A peek's walk (getRowOrder) and shift-click ranges follow the rows as shown, so folded rows are skipped. List view only.

<DataList
  columns={[
    {
      key: "title",
      header: "Task",
      interactive: true,
      render: (task, _i, { nesting }) => (
        <TaskTitle
          task={task}
          subtasks={
            nesting?.children ? (
              <SubtaskToggle
                count={nesting.children}
                expanded={nesting.expanded}
                onToggle={() => nesting.setExpanded(!nesting.expanded)}
              />
            ) : null
          }
        />
      ),
    },
  ]}
  data={tasks}
  getRowId={(t) => t.id}
  getRowParentId={(t) => t.parentId}
/>

List

view="list" — the default — is the table on this page. Every other view below takes the same data, sections, sort, filters, loadMore, loading, emptyState and noResults, so switching views never changes what is shown, only how.

Thumbnails

A column's thumbnail returns the row's image URL, and the cell shows a 32px Thumbnail before its value. thumbnailFallback is what a row with no image shows — pass the app's brand mark. The grid view uses the same column as the card image.

<DataList
  columns={[{ key: "name", header: "Family", thumbnail: (f) => f.imageUrl }]}
  thumbnailFallback={<BrandMark />}
/>

PreviewCode

Family	Products	Sub-families	Actions
Aurora Downlight2 missing specs	8	3
Beacon Track	5	1
Cove Linear	12	4
Drift Pendant1 missing spec	3	0
Harbor Bollard	6	2
Summit Flood4 missing specs	9	3

thumbnail can also return { src, placeholder?, srcSet?, sizes? }: the placeholder data URL blurs under the image until it loads, in the row and on the grid card alike.

thumbnail: (f) => ({
  src: f.image.url480,
  placeholder: f.image.blur,
  srcSet: f.image.srcset,
  sizes: "48px",
});

PreviewCode

Family	Products	Sub-families	Actions
Aurora Downlight2 missing specs	8	3
Beacon Track	5	1
Cove Linear	12	4
Drift Pendant1 missing spec	3	0
Harbor Bollard	6	2
Summit Flood4 missing specs	9	3

Grid

view="grid" renders one MediaCard per row in a responsive grid: one column on a phone, two from a medium container, three from a wide one. The first column is the card title, the other columns join into its meta line (a column's mergedRender is used there, so give counts their noun), a thumbnail column is its image, getRowHref makes the whole card a link, and rowActions is its ⋯ menu — on hover and focus, always on touch. Links never underline.

PreviewCode

Aurora Downlight2 missing specs

8 products · 3 sub-families

Beacon Track

5 products · 1 sub-family

Cove Linear

12 products · 4 sub-families

Drift Pendant1 missing spec

3 products · 0 sub-families

Harbor Bollard

6 products · 2 sub-families

Summit Flood4 missing specs

9 products · 3 sub-families

Grid and list

The same rows in both views. The first column is the record's title in each: the card's title in the grid and the first cell in the list, at one weight (font-medium, RECORD_TITLE_CLASS), while the meta — the card's meta line, the list's other cells and merged values — stays regular. A pill rendered in the first column sits beside the title in both, and a long title truncates before it.

PreviewCode

Aurora Downlight2 missing specs

8 products · 3 sub-families

Beacon Track

5 products · 1 sub-family

Summit Architectural Floodlight with Integrated Emergency Driver4 missing specs

9 products · 3 sub-families

Family	Products	Sub-families	Actions
Aurora Downlight2 missing specs	8	3
Beacon Track	5	1
Summit Architectural Floodlight with Integrated Emergency Driver4 missing specs	9	3

Grid with groups

With sections, each group renders as a heading and its count ("Indoor Luminaires · 4") above its own grid.

PreviewCode

Indoor Luminaires · 4, 4 rows

Aurora Downlight2 missing specs

8 products · 3 sub-families

Beacon Track

5 products · 1 sub-family

Cove Linear

12 products · 4 sub-families

Drift Pendant1 missing spec

3 products · 0 sub-families

Outdoor Luminaires · 2, 2 rows

Harbor Bollard

6 products · 2 sub-families

Summit Flood4 missing specs

9 products · 3 sub-families

Grid lg

gridSize="lg" puts a 16:9 image on top of each card, in fewer, wider columns.

PreviewCode

Aurora Downlight2 missing specs

8 products · 3 sub-families

Beacon Track

5 products · 1 sub-family

Cove Linear

12 products · 4 sub-families

Drift Pendant1 missing spec

3 products · 0 sub-families

Harbor Bollard

6 products · 2 sub-families

Summit Flood4 missing specs

9 products · 3 sub-families

Dense grid

gridDensity="dense" fits more cards by width, for a file browser: at gridSize="lg", 1 column below a 20rem container, 2 from 20rem, 3 from 42rem, 4 from 64rem and 5 from 80rem. The loading skeleton follows the same columns, and at lg each skeleton card is the MediaCard lg shape — a 16:9 block and two text lines — so nothing jumps when the cards arrive.

PreviewCode

Aurora Downlight2 missing specs

8 products · 3 sub-families

Beacon Track

5 products · 1 sub-family

Cove Linear

12 products · 4 sub-families

Drift Pendant1 missing spec

3 products · 0 sub-families

Harbor Bollard

6 products · 2 sub-families

Summit Flood4 missing specs

9 products · 3 sub-families

Custom card

renderCard replaces the default card — compose a MediaCard with its badge (beside the title) and timestamp slots, or anything else.

PreviewCode

Aurora Downlight2 missing specs

8 products2h ago

Beacon Track

5 products2h ago

Cove Linear

12 products2h ago

Drift Pendant1 missing spec

3 products2h ago

Harbor Bollard

6 products2h ago

Summit Flood4 missing specs

9 products2h ago

Layout

onViewChange gives a ListToolbar toolbar its Layout tool — icon buttons at the end of the toolbar row, folded into Display on a narrow one — unless the toolbar sets its own layout. Never put it in the PageHeader: the header's tabs hold the scope ("My | Team") only. views sets which layouts it offers, in order (default Grid | List). The chosen view is remembered for the browser session under viewStorageKey (default: the path plus the list's aria-label). defaultView is the page's first view before the user picks one — "board" for a task list, "grid" for a catalogue — and the remembered choice wins after that. Any other toolbar renders as it is, with no switch added.

<DataList
  view={view}
  onViewChange={setView}
  toolbar={
    <ListToolbar
      search={search}
      filterRow={<FilterRow facets={facets} onClear={clearAll} />}
    />
  }
/>

PreviewCode

Indoor Luminaires · 4, 4 rows

Aurora Downlight2 missing specs

8 products · 3 sub-families

Beacon Track

5 products · 1 sub-family

Cove Linear

12 products · 4 sub-families

Drift Pendant1 missing spec

3 products · 0 sub-families

Outdoor Luminaires · 2, 2 rows

Harbor Bollard

6 products · 2 sub-families

Summit Flood4 missing specs

9 products · 3 sub-families

Board

view="board" renders the sections as Board lanes — every lane shows, empty or not — and each row as a BoardCard. The board owns the card surface, its link and its ⋯ menu (rowActions, submenus included). By default the lanes fill the viewport below the list and cards scroll inside each lane (boardHeight, default "fill"). Offer it with views={["list", "board"]}.

• Cards. boardCard(row) maps a row to the card's fields — title, context, due, priority, assignee, done / onDoneChange, status (your status circle, the same control the list rows use), and the quieter slots — eyebrow, aside, chips, alert, footnote. Without it the title is the first column and the context line joins the other columns. renderCard replaces the card entirely.
• Moves. onMove(row, fromSection, toSection, move) applies a drag or a keyboard move between lanes. The card moves at once; return a promise to gate it on the server — a rejection snaps it back with a toast. Without onMove the board is read-only.
• Lanes. onAddToSection(sectionId) adds an "+ Add" button (its text is addLabel) at each lane's foot so the host's create form opens with that status filled in. Every lane collapses from the icon button left of its header's ⋯ menu (collapsedSections / onCollapsedSectionsChange control it); a section's defaultCollapsed starts it as a read-only strip, droppable: false and lockedReason refuse cards, and addable: false hides its add button. addPlacement="header" puts the add button in each lane's header beside ⋯ instead. A section's icon leads its lane title, its actions fill the lane's ⋯ menu, and boardTrailing renders after the last lane inside the board's scroller.
• Hidden lanes. hiddenSections lists the lanes the host hides (Cancelled, Duplicate) under "Hidden columns" after the last lane; choosing one calls onShowSection. A section marked hideable offers "Hide column" in its ⋯ menu, which calls onHideSection. activeRowId marks the open card.
• Per-lane data. A section's own loading, loadMore (loaded as the lane's foot scrolls into view, with skeleton cards while it loads) and emptyState give each lane its own first load, paging and empty state. An empty lane reads "Nothing here", and "Drop here" while dragging.

The simplest board: two columns, three sections and onMove, switched with the view toggle.

Loading: every lane shows skeleton cards while the list loads, and a section's loading does the same for one lane.

On a phone (below 768px) the board shows one lane at a time at full width: swipe between lanes, or tap one in the lane strip above, which shows each lane's count. Hold a card for a quarter of a second to pick it up (a swipe still scrolls), and drag it to the screen's edge to turn to the next lane; the card's ⋯ menu is the one-tap path. The grid drops to one column and the list keeps its merged columns.

Fitting the width

DataList never forces a horizontal scroll. It measures its container and fits the columns into it with the same responsive column revelation as DataGrid: every column declares a pixel budget (minWidth, default 120) and a posture for when it no longer fits (mobile, default "merge"). The first column and every "visible" column always stay, and their budgets are reserved first, wherever they sit — a trailing Status or actions column is never squeezed by an earlier column that took its room. The rest are kept left to right while their budgets fit, and once one column overflows every column after it overflows too, so a narrow late column never survives a wide earlier one.

const columns: DataListColumn<Person>[] = [
  { key: "name", header: "Name", minWidth: 160 }, // primary: always shown
  { key: "email", header: "Email" }, // merges when it no longer fits
  { key: "amount", header: "Amount", align: "end", mobile: "visible" }, // never hides
  { key: "notes", header: "Notes", mobile: "hidden" }, // dropped and counted
];

A leading selection column is budgeted first (40px). "hidden" is the only posture that removes a value, which is why it is opt-in and why it reports itself — use it only when the value is recoverable elsewhere (a detail page, a drawer). The server render shows every column, because an unmeasured table has no evidence that anything overflows; on the client the split is corrected in a layout effect, before first paint.

A merged value loses the header above it, and the screen-reader prefix does not help a sighted reader on a phone: a bare 4 under the name reads as nothing. Give the column mergedRender to say what the value is where it lands — it replaces render (and the prefix) only in the merged stack, so the wide table still shows 4 under its "To review" header:

{
  key: "toReview",
  header: "To review",
  align: "end",
  mergedRender: (m) => `${m.toReview} to review`,
}

Several short facts read better on one line than stacked. mergedLayout="line" joins the merged values into one compact meta line under the primary value, separated by a decorative dot — "Today · High · Arjun Mehta" — and truncates when the line runs out. Every value sits on the line's centre: a chip, a person (its avatar hidden) and a time with its 24px tooltip target stay level with the plain text and the dots, and a value that renders nothing, "" or "—" — bare or as the only content of a plain element — drops with its dot. A figure — a column marked align: "end", mono or numeric (a size, a count, an id, a date) — keeps its whole width on a tight line, and the text values beside it truncate first: "Produ… · 1w ago · K Manoj… · 25 MB", never "w ag". Mark a time column numeric so it stays whole. The default, "stack", is one value per line.

Fill and fit. The primary (first) column is the fill column: it takes the width the others leave, its text wraps — anywhere, so one long unbroken name never widens the table — and a plain value (no render, or a render that returns a string) clamps at two lines with an ellipsis, the full value in its tooltip — or, when the first cell is the row's own link or button, in its title, so no second control nests inside the row's. Every other column is a fit column: sized to its content and kept on one line, and every header stays on one line too. A short value or label never breaks.

If the table still overflows once revelation has run — a long unbroken value inside a custom render of the first column, a one-line mono identifier there — it is squeezed (data-squeezed on the <table>): the fill cell may then break anywhere instead of scrolling. Fit cells and headers are never squeezed. If it still overflows, or the fit columns leave the fill column narrower than its own minWidth, one more column merges into the primary cell, from the right, until it fits. Only when nothing is left to merge — the primary and "visible" columns — and it still overflows is it strained (data-strained): the fit cells release as well, and a header wraps between its words, never inside one. The checks run before paint and are re-taken only when the width, the columns or the data change.

The squeeze reaches inside a custom render too: the text in the fill cell wraps, whatever it says for itself, so a whitespace-nowrap row breaks across lines (an auto-layout table cannot truncate a one-line box, so its ellipsis was never available there). A truncate element keeps its promise of one line instead: it is clamped to a single line (line-clamp-1) that ends in an ellipsis, so a meta line of a fixed height never spills over the title beside it.

Controls and fixed-size content are never wrapped by the squeeze, because their height is fixed and a label wrapped inside one would spill out of it. They are recognised by what reaches the DOM, whatever element carries it:

• every other Button, and any element styled with buttonVariants(), toggleVariants(), navigationMenuTriggerStyle(), tabsListVariants() or stepperNodeVariants();
• a native button, input, select or textarea, and an element with the role button, checkbox, combobox, radio, slider, spinbutton, switch or tab;
• an Avatar and a Kbd.

These keep the one-line posture they give themselves (every VegaStack control sets one), and an Avatar, a Kbd and a stepper node are held on one line and at full width. An unstyled button or role="button" element has no fixed box, so it simply wraps with its cell. The text around a kept part breaks instead, and the row grows taller. An icon cannot shrink either.

A kept part or a header word wider than the container is what nothing can fit. A header never breaks inside a word, so keep header words short enough to sit side by side in the narrowest container you support. Controls are never wrapped, so keep the controls and fixed-size parts of every always-shown column small enough to fit, side by side on one line, in the narrowest container you support; an outline Button whose label alone is wider than the table leaves it nothing to squeeze, and the table scrolls sideways. Put long text in a link-variant Button or a plain <a>, which wrap.

A stacked merged value always wraps (mergedLayout="line" is one line that truncates, squeezed or not). It does not inherit the first column's posture: under a mono or align: "end" first column (both one line by default) every stacked value still breaks inside the cell — at a space, or anywhere when a single word is wider than the cell — and wears its own column's face, so prose under a mono invoice number is not set in mono. The first column's own value keeps its one-line rule, so give a long mono identifier a minWidth that fits it.

Dropped columns and the sort stay visible. A mobile: "hidden" column is counted under the table. And when the active sort's column is merged or hidden — so its header, arrow and aria-sort are gone — a second line says what the order is (Sorted by Amount, descending). DataList states the order rather than forcing the sorted column back into the header row, which would re-open the horizontal scroll. The table is described by both lines.

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={
    <DataListPager
      page={page}
      pageSize={pageSize}
      total={total}
      onPageChange={setPage}
      onPageSizeChange={setPageSize}
    />
  }
  onRowClick={(row) => router.push(`/items/${row.id}`)}
/>

Here the host owns a search box (in toolbar) and a DataListPager (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 system's 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