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`
version	3.30.0
usage	`import {useTableState, useTableColumnResizeState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

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

useTableColumnResizeState<T>(
  (props: TableColumnResizeStateProps<T>,
  , state: TableState<T>
)): TableColumnResizeState<T>

Cell(
  (props: CellProps
)): ReactElement

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

Row<T>(
  (props: RowProps<T>
)): ReactElement

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

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

Interface#

useTableState#

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.
`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.
`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, , direction?: 'ascending' \| \| 'descending' )): void`	Calls the provided onSortChange handler with the provided column key and sort direction.

useTableColumnResizeState#

Name	Type	Description
`updateResizedColumns`	`( (key: Key, , width: number )) => Map<Key, ColumnSize>`	Called to update the state that a resize event has occurred. Returns the new widths for all columns based on the resized column.
`startResize`	`( (key: Key )) => void`	Callback for when onColumnResize has started.
`endResize`	`() => void`	Callback for when onColumnResize has ended.
`getColumnWidth`	`( (key: Key )) => number`	Gets the current width for the specified column.
`getColumnMinWidth`	`( (key: Key )) => number`	Gets the current minWidth for the specified column.
`getColumnMaxWidth`	`( (key: Key )) => number`	Gets the current maxWidth for the specified column.
`resizingColumn`	`Key \| null`	Key of the currently resizing column.
`tableState`	`TableState<T>`	A reference to the table state.

Example#

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

Name	Type	Description
`children`	`[ ReactElement<TableHeaderProps<T>>, ReactElement<TableBodyProps<T>> ]`	The elements that make up the table. Includes the TableHeader, TableBody, Columns, and Rows.
`disabledKeys`	`Iterable<Key>`	A list of row keys to disable.
`collection`	`TableCollection<T>`	A pre-constructed collection to use instead of building one from items and children.
`showSelectionCheckboxes`	`boolean`	Whether the row selection checkboxes should be displayed.
`selectionBehavior`	`SelectionBehavior`	How multiple selection should behave in the collection.
`allowDuplicateSelectionEvents`	`boolean`	Whether onSelectionChange should fire even if the new set of keys is the same as the last.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to all interactions, or only selection.
`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.

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.

ReactElement<ColumnProps<T>>

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`	`ColumnSize \| null`	The width of the column.
`minWidth`	`ColumnStaticSize \| null`	The minimum width of the column.
`maxWidth`	`ColumnStaticSize \| null`	The maximum width of the column.
`defaultWidth`	`ColumnSize \| null`	The default width of the column.
`allowsResizing`	`boolean`	Whether the column allows resizing.
`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.

All possible sizes a column can be assigned.

ColumnStaticSize | ColumnDynamicSize

Widths that result in a constant pixel value for the same Table width.

number
  | `${number}`
  | `${number}%`

Widths that change size in relation to the remaining space and in ratio to other dynamic columns. All numbers must be integers and greater than 0. FR units take up remaining, if any, space in the table.

`${number}fr`

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

Name	Type	Description
`children`	`RowElement<T> \| RowElement<T>[] \| ( (item: T )) => RowElement<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.

ReactElement<RowProps<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.
`href`	`string`	A URL to link to. See MDN.
`target`	`HTMLAttributeAnchorTarget`	The target window for the link. See MDN.
`rel`	`string`	The relationship between the linked resource and the current page. See MDN.
`download`	`boolean \| string`	Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
`ping`	`string`	A space-separated list of URLs to ping when the link is followed. See MDN.
`referrerPolicy`	`HTMLAttributeReferrerPolicy`	How much of the referrer to send when following the link. See MDN.

ReactElement<CellProps>

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.

(
  (columnKey: Key
)) => CellElement

string | number

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

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 )): GridNode<T> \| null`	Get an item by its key.
`at( (idx: number )): GridNode<T> \| null`	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.
`getChildren( (key: Key )): Iterable<GridNode<T>>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	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.
`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`	The number of columns spanned by this cell.
`colIndex`	`number`	The column index of this cell, accounting for any colspans.
`indexOfType`	`number`	The index of this node within its parent, ignoring sibling nodes that aren't of the same type.
`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 \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	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 \| null`	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.
`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 \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

'toggle' | 'replace'

'selection' | 'all'

'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.
`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.
`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, , direction?: 'ascending' \| \| 'descending' )): void`	Calls the provided onSortChange handler with the provided column key and sort direction.

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`
`disabledKeys`	`Set<Key>`
`disabledBehavior`	`DisabledBehavior`

Methods

Method	Description
`constructor( collection: Collection<Node<unknown>>, state: MultipleSelectionState, options?: SelectionManagerOptions ): void`
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , 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`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`

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

Extends: Iterable

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 \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	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.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.

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.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`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 )): 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
`allowsCellSelection`	`boolean`

Properties

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`	`Element`	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.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'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`	`Element`	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
`tableWidth`	`number`	Current width of the table or table viewport that the columns should be calculated against.
`getDefaultWidth`	`( (node: GridNode<T> )) => ColumnSize \| null \| undefined`	A function that is called to find the default width for a given column.
`getDefaultMinWidth`	`( (node: GridNode<T> )) => ColumnSize \| null \| undefined`	A function that is called to find the default minWidth for a given column.

Name	Type	Description
`updateResizedColumns`	`( (key: Key, , width: number )) => Map<Key, ColumnSize>`	Called to update the state that a resize event has occurred. Returns the new widths for all columns based on the resized column.
`startResize`	`( (key: Key )) => void`	Callback for when onColumnResize has started.
`endResize`	`() => void`	Callback for when onColumnResize has ended.
`getColumnWidth`	`( (key: Key )) => number`	Gets the current width for the specified column.
`getColumnMinWidth`	`( (key: Key )) => number`	Gets the current minWidth for the specified column.
`getColumnMaxWidth`	`( (key: Key )) => number`	Gets the current maxWidth for the specified column.
`resizingColumn`	`Key \| null`	Key of the currently resizing column.
`tableState`	`TableState<T>`	A reference to the table state.