useTableState

Provides state management for a table component. Handles building a collection of columns and rows from props. In addition, it tracks row selection and manages sort order changes.

install	`yarn add @react-stately/table`
version	3.1.0
usage	`import {useTableState} from '@react-stately/table'`

View repository

GitHub

View package

NPM

API#

useTableState<T>(
  (props: TableStateProps<T>
)): TableState<T>

Cell(
  (props: CellProps
)): ReactElement

Column<T>(
  (props: ColumnProps<T>
)): ReactElement

Row(
  (props: RowProps
)): ReactElement

TableBody<T>(
  (props: TableBodyProps<T>
)): ReactElement

TableHeader<T>(
  (props: TableHeaderProps<T>
)): ReactElement

Interface#

Properties

Name	Type	Description
`collection`	`TableCollection<T>`	A collection of rows and columns in the table.
`showSelectionCheckboxes`	`boolean`	Whether the row selection checkboxes should be displayed.
`sortDescriptor`	`SortDescriptor`	The current sorted column and direction.
`disabledKeys`	`Set<Key>`	A set of keys for rows that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update row selection state.

Methods

Method	Description
`sort( (columnKey: Key )): void`	Calls the provided onSortChange handler with the provided column key and sort direction.

Example#

See the docs for useTable in react-aria for an example of useTableState, Cell, Column, Row, TableBody, and TableHeader.

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`showSelectionCheckboxes`	`boolean`	Whether the row selection checkboxes should be displayed.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionBehavior`	`SelectionBehavior`	How multiple selection should behave in the collection.
`alwaysFireOnSelection`	`boolean`	Whether onSelectionChange should always be fired, even if the key is the same.
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`( (keys: Selection )) => any`	Handler that is called when the selection changes.
`sortDescriptor`	`SortDescriptor`	The current sorted column and direction.
`onSortChange`	`( (descriptor: SortDescriptor )) => any`	Handler that is called when the sorted column or direction changes.

CollectionElement<T>
  | CollectionElement<T>[]
  | (
    (item: T
  )) => CollectionElement<T>

SectionElement<T> | ItemElement<T>

ReactElement<SectionProps<T>>

Name	Type	Description
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`items`	`Iterable<T>`	Item objects in the section.

ReactElement<ItemProps<T>>

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.

(
  (item: T
)) => ItemElement<T>

'toggle' | 'replace'

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

Name	Type	Description
`column`	`Key`	The key of the column to sort by.
`direction`	`SortDirection`	The direction to sort by.

'ascending' | 'descending'

Properties

Name	Type	Description
`collection`	`TableCollection<T>`	A collection of rows and columns in the table.
`showSelectionCheckboxes`	`boolean`	Whether the row selection checkboxes should be displayed.
`sortDescriptor`	`SortDescriptor`	The current sorted column and direction.
`disabledKeys`	`Set<Key>`	A set of keys for rows that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update row selection state.

Methods

Method	Description
`sort( (columnKey: Key )): void`	Calls the provided onSortChange handler with the provided column key and sort direction.

Properties

Name	Type	Description
`headerRows`	`GridNode<T>[]`	A list of header row nodes in the table.
`columns`	`GridNode<T>[]`	A list of column nodes in the table.
`rowHeaderColumnKeys`	`Set<Key>`	A set of column keys that serve as the row header.
`body`	`GridNode<T>`	The node that makes up the body of the table.
`columnCount`	`number`	The number of columns in the grid.
`rows`	`GridNode<T>[]`	A list of rows in the grid.
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): Node`	Get an item by its key.
`at( (idx: number )): Node`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the heirarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`childNodes`	`Iterable<Node<T>>`	The loaded children of this node.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`column`	`GridNode<T>`
`colspan`	`number`
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key`	The key of the parent node.
`prevKey`	`Key`	The key of the node before this node.
`nextKey`	`Key`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the heirarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`childNodes`	`Iterable<Node<T>>`	The loaded children of this node.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key`	The key of the parent node.
`prevKey`	`Key`	The key of the node before this node.
`nextKey`	`Key`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , childFocusStrategy: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): void`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e: PressEvent \| LongPressEvent \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`

A generic interface to access a readonly sequential collection of unique keyed items.

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T`	Get an item by its key.
`at( (idx: number )): T`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection \| \| ( (v: Selection )) => Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , child: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'first' | 'last'

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

Name	Type	Description
`children`	`ReactNode`	The contents of the cell.
`textValue`	`string`	A string representation of the cell's contents, used for features like typeahead.

Name	Type	Description
`children`	`ReactNode \| ColumnElement<T> \| ColumnElement<T>[]`	Static child columns or content to render as the column header.
`title`	`ReactNode`	Rendered contents of the column if `children` contains child columns.
`childColumns`	`T[]`	A list of child columns used when dynamically rendering nested child columns.
`width`	`number \| string`	The width of the column.
`minWidth`	`number \| string`	The minimum width of the column.
`maxWidth`	`number \| string`	The maximum width of the column.
`allowsSorting`	`boolean`	Whether the column allows sorting.
`isRowHeader`	`boolean`	Whether a column is a row header and should be announced by assistive technology during row navigation.
`textValue`	`string`	A string representation of the column's contents, used for accessibility announcements.

ReactElement<ColumnProps<T>>

Name	Type	Description
`children`	`CellElement \| CellElement[] \| CellRenderer`	Rendered contents of the row or row child items.
`textValue`	`string`	A string representation of the row's contents, used for features like typeahead.

ReactElement<CellProps>

(
  (columnKey: Key
)) => CellElement

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the table body. Supports static items or a function for dynamic rendering.
`items`	`Iterable<T>`	A list of row objects in the table body used when dynamically rendering rows.
`loadingState`	`LoadingState`	The current loading state of the table.
`onLoadMore`	`() => any`	Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.

'loading'
  | 'sorting'
  | 'loadingMore'
  | 'error'
  | 'idle'
  | 'filtering'

Name	Type	Description
`children`	`ColumnElement<T> \| ColumnElement<T>[] \| ColumnRenderer<T>`	A list of `Column(s)` or a function. If the latter, a list of columns must be provided using the `columns` prop.
`columns`	`T[]`	A list of table columns.

(
  (item: T
)) => ColumnElement<T>