useTable

Provides the behavior and accessibility implementation for a table component. A table displays data in rows and columns and enables a user to navigate its contents via directional navigation keys, and optionally supports row selection and sorting.

Name	Type	Level
Charizard	Fire, Flying	67
Blastoise	Water	56
Venusaur	Grass, Poison	83
Pikachu	Electric	100

Example

Table.tsx

Table.css

Example

Table.tsx

Table.css

import {Table, TableHeader, TableBody, Column, Row, Cell} from './Table';

<Table aria-label="Pokémon" selectionMode="multiple" selectionBehavior="replace">
  <TableHeader>
    <Column isRowHeader>Name</Column>
    <Column>Type</Column>
    <Column>Level</Column>
  </TableHeader>
  <TableBody>
    <Row key="charizard"><Cell>Charizard</Cell><Cell>Fire, Flying</Cell><Cell>67</Cell></Row>
    <Row key="blastoise"><Cell>Blastoise</Cell><Cell>Water</Cell><Cell>56</Cell></Row>
    <Row key="venusaur"><Cell>Venusaur</Cell><Cell>Grass, Poison</Cell><Cell>83</Cell></Row>
    <Row key="pikachu"><Cell>Pikachu</Cell><Cell>Electric</Cell><Cell>100</Cell></Row>
  </TableBody>
</Table>

API

<ResizableTableContainer>
  <Table>
    <TableHeader>
      <Column />
      <Column><Checkbox slot="selection" /></Column>
      <Column><ColumnResizer /></Column>
      <Column />
    </TableHeader>
    <TableBody>
      <Row>
        <Cell><Button slot="drag" /></Cell>
        <Cell>
          <Checkbox slot="selection" /> or <SelectionIndicator />
        </Cell>
        <Cell>
          <Button slot="chevron" />
        </Cell>
        <Cell />
        <Row>
          {/* ... */}
        </Row>
      </Row>
      <TableLoadMoreItem />
    </TableBody>
    <TableFooter>
      <Row>
        <Cell />
      </Row>
    </TableFooter>
  </Table>
</ResizableTableContainer>

useTableState<T extends object>(props: TableStateProps<T>): TableState<T>useTableColumnResizeState<T>(props: TableColumnResizeStateProps<T>, state: TableState<T>): TableColumnResizeState<T>

useTable<T>(
  props: AriaTableProps,
state: TableState<T> | TreeGridState<T>,
ref: RefObject<HTMLElement | null>
): GridAria

useTableRowGroup(): GridRowGroupAria

useTableHeaderRow<T>(
  props: GridRowProps<T>,
state: TableState<T>,
ref: RefObject<Element | null>
): TableHeaderRowAria

useTableColumnHeader<T>(
  props: AriaTableColumnHeaderProps<T>,
state: TableState<T>,
ref: RefObject<FocusableElement | null>
): TableColumnHeaderAria

useTableRow<T>(
  props: GridRowProps<T>,
state: TableState<T> | TreeGridState<T>,
ref: RefObject<FocusableElement | null>
): TableRowAria

useTableCell<T>(
  props: AriaTableCellProps,
state: TableState<T>,
ref: RefObject<FocusableElement | null>
): TableCellAria

useTableSelectionCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>): TableSelectionCheckboxAriauseTableSelectAllCheckbox<T>(state: TableState<T>): TableSelectAllCheckboxAria

useTableColumnResize<T>(
  props: AriaTableColumnResizeProps<T>,
state: TableColumnResizeState<T>,
ref: RefObject<HTMLInputElement | null>
): TableColumnResizeAria

TableState

Properties

Name	Type
`collection`	`ITableCollection<T>`
A collection of rows and columns in the table.
`showSelectionCheckboxes`	`boolean`
Whether the row selection checkboxes should be displayed.
`sortDescriptor`	`SortDescriptor \| null`
The current sorted column and direction.
`isKeyboardNavigationDisabled`	`boolean`
Whether keyboard navigation is disabled, such as when the arrow keys should be handled by a component within a cell.
`setKeyboardNavigationDisabled`	`(val: boolean) => void`
Set whether keyboard navigation is disabled, such as when the arrow keys should be handled by a component within a cell.
`expandedKeys`	`Set<Key>`
A set of keys for items that are expanded.
`treeColumn`	`Key \| null`
The id of the column that displays hierarchical data.
`selectionManager`	`SelectionManager`
A selection manager to read and update row selection state.

`disabledKeys`	`Set<Key>`
A set of keys for rows that are disabled.

Methods

`sort(columnKey: Key, direction?: 'ascending' \| 'descending'): void`
Calls the provided onSortChange handler with the provided column key and sort direction.
`toggleKey(key: Key): void`
Toggles the expanded state for a row by its key.

AriaTableProps

Name	Type	Default
`layoutDelegate`	`LayoutDelegate`	Default: —
The layout object for the table. Computes what content is visible and how to position and style them.
`isVirtualized`	`boolean`	Default: —
Whether the grid uses virtual scrolling.
`disallowTypeAhead`	`boolean`	Default: `false`
Whether typeahead navigation is disabled.
`keyboardDelegate`	`KeyboardDelegate`	Default: —
An optional keyboard delegate implementation for type to select, to override the default.
`focusMode`	`'row' \| 'cell'`	Default: `'row'`
Whether initial grid focus should be placed on the grid row or grid cell.
`getRowText`	`(key: Key) => string`	Default: `(key) => state.collection.getItem(key)?.textValue`
A function that returns the text that should be announced by assistive technology when a row is added or removed from selection.
`scrollRef`	`RefObject<HTMLElement \| null>`	Default: —
The ref attached to the scrollable body. Used to provided automatic scrolling on item focus for non-virtualized grids.
`keyboardNavigationBehavior`	`'arrow' \| 'tab'`	Default: `'arrow'`
Whether keyboard navigation to focusable elements within grid cells is via arrow keys or the tab key.

`shouldSelectOnPressUp`	`boolean`	Default: —
Whether selection should occur on press up instead of press down.
`escapeKeyBehavior`	`'clearSelection' \| 'none'`	Default: `'clearSelection'`
Whether pressing the escape key should clear selection in the grid or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.

AriaTableColumnHeaderProps

Name	Type
`node`	`GridNode<T>`
An object representing the column header. Contains all the relevant information that makes up the column header.
`isVirtualized`	`boolean`
Whether the column header is contained in a virtual scroller.
`focusMode`	`'child' \| 'cell'`
Whether the column header or its first focusable child element should be focused when the column header is focused. Defaults to 'child' in arrow keyboard navigation mode and 'cell' in tab keyboard navigation mode.
`allowsArrowNavigation`	`boolean`
Whether the column header should support arrow key navigation even when the containing table uses tab keyboard navigation. Allows users to navigate between columns with arrow keys while focus is on an interactive child element within the cell.

AriaTableCellProps

Name	Type
`node`	`GridNode<unknown>`
An object representing the table cell. Contains all the relevant information that makes up the row header.
`isVirtualized`	`boolean`
Whether the cell is contained in a virtual scroller.
`focusMode`	`'child' \| 'cell'`
Whether the cell or its first focusable child element should be focused when the cell is focused. Defaults to 'child' in arrow keyboard navigation mode and 'cell' in tab keyboard navigation mode.
`allowsArrowNavigation`	`boolean`
Whether the cell should support arrow key navigation even when the containing table uses tab keyboard navigation.Allows users to navigate between rows and cells with arrow keys while focus is on an interactive child element within the cell.

`shouldSelectOnPressUp`	`boolean`
Whether selection should occur on press up instead of press down.