Data table

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Combine Table, FilterBar, Checkbox, Menu, and Pagination for comparison tasks. The table follows the Table guidelines.
• Process data in order: filter → stable sort → paginate. Changing the search, sort, or page size returns to the first page.
• Sort with Table.SortHeader. Text sorts ascending first and numbers descending first; a status line announces the new order.
• Keep selection with useTableSelection, by row ID. The header checkbox selects only manageable rows on the current page.
• Keep the header and column widths in every state. Loading shows skeleton rows for the page size with aria-busy; errors, missing access and empty results sit in Table.Message rows.
• Announce how many selections sit outside the current page. Bulk actions apply to an explicit selection set that includes hidden selections.
• The Columns menu always keeps the required name column. Hiding the sorted column resets the sort to name ascending.

• Don't turn the whole table into an ARIA grid. Keep native table semantics.
• Don't hide navigation in whole-row clicks. Checkboxes, name links, and sort buttons each act on their own.
• Don't auto-select server results that aren't visible.
• Don't assume virtualization or server-wide selection. Neither is implemented, and the example handles only small local data.
• Don't filter, sort, or paginate large datasets locally. The product owns server-side filtering, sorting, and pagination, plus URL state, request cancellation, permissions, idempotent bulk changes, and selection validation.

Anatomy

Preview mode → FilterBar(query, product, reset, result summary) → bulk actions + Columns menu → Table.Container(caption, fixed column widths, SortHeader columns, page selection, row headers with native links, numeric instances, state; skeleton or Message rows) → page size + Pagination → status line

Keyboard and accessibility

• Tab, Shift+Tab, Enter, and Space operate the controls. Each sort control is a button inside its header cell.
• Search and page changes keep focus on the control in use. Focus returns to the search input after loading finishes, a retry, restored access, or a cleared search.
• The Columns menu follows Base UI's arrow keys and Escape, and returns focus to its trigger.
• On mobile, the shared ScrollArea handles horizontal overflow.
• The table keeps native semantics with scope=col and scope=row. Only the sorted column has aria-sort, and sort buttons are disabled while the table has no rows.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Table, Checkbox, Pagination, useTableSelection } from '@surflane/ui'

// Product-owned state: query, filters, sorting, selected stable IDs, page, columns.
const sorted = stableSort(filter(rows, query), sort)
const visible = sorted.slice((page - 1) * size, page * size)
const selection = useTableSelection({
  rows: visible,
  getId: (row) => row.id,
  canSelect: (row) => row.canManage,
  selected,
  onSelectedChange: setSelected,
})

<Table.Container label='Resource comparison' orientation='horizontal'>
  <Table.Root aria-busy={loading || undefined}>
    <Table.Caption>Resources</Table.Caption>
    <Table.Head>
      <Table.Row>
        <Table.HeaderCell scope='col'>
          <Checkbox.Root
            aria-label='Select manageable rows on this page'
            {...selection.pageCheckbox}
          >
            <Checkbox.Indicator />
          </Checkbox.Root>
        </Table.HeaderCell>
        <Table.SortHeader
          sort={sortOf('name')}
          onSort={() => toggleSort('name')}
        >
          Name
        </Table.SortHeader>
        <Table.SortHeader
          numeric
          sort={sortOf('instances')}
          onSort={() => toggleSort('instances')}
        >
          Instances
        </Table.SortHeader>
      </Table.Row>
    </Table.Head>
    <Table.Body>
      {error ? (
        <Table.Message colSpan={3}>…retry…</Table.Message>
      ) : (
        visible.map((row) => (
          <Table.Row key={row.id} selected={selection.isSelected(row.id)}>
            <Table.Cell>
              <Checkbox.Root
                aria-label={`Select ${row.name}`}
                {...selection.rowCheckbox(row)}
              >
                <Checkbox.Indicator />
              </Checkbox.Root>
            </Table.Cell>
            <Table.HeaderCell scope='row'>
              <a href={row.href}>{row.name}</a>
            </Table.HeaderCell>
            <Table.Cell numeric>{row.instances}</Table.Cell>
          </Table.Row>
        ))
      )}
    </Table.Body>
  </Table.Root>
</Table.Container>
<Pagination page={page} pageCount={pageCount} onPageChange={setPage} />

// Reset page on filter/sort/page-size changes and clamp after response changes.
// Header selection is only the current page's manageable rows, not all results.
// Revalidate selected IDs against authorization on the server before mutation.

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens