Table

Preview

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

Usage

Compare relationships across rows and columns. Render a native table: Caption, HeaderCell with scope=col or scope=row, and Cell. Wrap it in Container, the labeled scroll region. Set numeric on number columns, use SortHeader for sortable columns, and set density="compact" for consoles people scan with a pointer. The calling screen owns sorting, search, and selection state; useTableSelection keeps selection by row ID. See Guidelines below for each rule with a working design. Set layout="fixed" with Column widths so columns hold still while rows change, nowrap for a console's one-line rows with Truncate for long names, and hideBelow on a column that can step aside when the Container narrows.

• Don't add a grid role or arrow-key cell navigation to an ordinary table. Keep native table semantics instead.
• Don't rely on whole-row clicks. Put links, buttons, and checkboxes in the cells instead.
• Don't rely on Row.selected alone, because it's visual only. Pair it with a named checkbox, which carries the selection semantics.
• Don't put units in every cell. Name the unit in the header and set numeric instead.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Container(ScrollArea) → Root(table, density, layout, stickyHeader) → Caption + Columns(Column)? + Head(Row/HeaderCell or SortHeader) + Body(Row/Cell, Truncate, or Message)

Guidelines

Rules for real screens, each with a working design. The designs use the shipped parts and stay local.

Keyboard and accessibility

Tab moves through sort buttons, row selection checkboxes, and actions. Rows aren't focus targets. On small screens, the labeled region takes focus and scrolls horizontally. SortHeader sets aria-sort on the sorted column only, and its button keeps the column's visible name.

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, useTableSelection } from '@surflane/ui'

const selection = useTableSelection({
  rows: pageRows,
  getId: (row) => row.id,
  canSelect: (row) => row.canManage,
})

<Table.Container label='Service inventory'>
  <Table.Root density='compact'>
    <Table.Caption>Services</Table.Caption>
    <Table.Head>
      <Table.Row>
        <Table.HeaderCell scope='col'>
          <Checkbox.Root
            aria-label='Select services on this page'
            {...selection.pageCheckbox}
          >
            <Checkbox.Indicator />
          </Checkbox.Root>
        </Table.HeaderCell>
        <Table.SortHeader sort='ascending' onSort={toggleNameSort}>
          Name
        </Table.SortHeader>
        <Table.SortHeader numeric onSort={sortByLatency}>
          p95 latency (ms)
        </Table.SortHeader>
      </Table.Row>
    </Table.Head>
    <Table.Body>
      {pageRows.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'>{row.name}</Table.HeaderCell>
          <Table.Cell numeric>{row.latency.toLocaleString()}</Table.Cell>
        </Table.Row>
      ))}
    </Table.Body>
  </Table.Root>
</Table.Container>

Key API

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

Related tokens