useTableColumnResizeState

Provides column width state management for a table component with column resizing support. Handles building a map of column widths calculated from the table's width and any provided column width information from the collection. In addition, it tracks the the currently resizing column and provides callback for updating the widths upon resize operations.

install	`yarn add react-stately`
version	3.20.0
usage	`import {useTableColumnResizeState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

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

Interface#

Name	Type	Description
`onColumnResize`	`( (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. *
`onColumnResizeStart`	`( (key: Key )) => void`	Callback for when onColumnResize has started.
`onColumnResizeEnd`	`() => 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.
`widths`	`Map<Key, number>`	Currently calculated widths for all columns.
`resizingColumn`	`Key \| null`	Key of the currently resizing column.
`tableState`	`TableState<T>`	A reference to the table state.

Example#

// TODO: link to the resizing section specifically See the docs for useTable in react-aria for an example of using useTableColumnResizeState with useTableState to create a table with resizable columns.

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
`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`	The number of columns spanned by this cell.
`colIndex`	`number`	The column index of this cell, accounting for any colspans.
`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.

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.

`${number}fr`

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.

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<T>`	Get an item by its key.
`at( (idx: number )): Node<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.

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

'ascending' | 'descending'

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, , 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`

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

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

'all' | Set<Key>

'selection' | 'all'

'first' | 'last'

Name	Type	Description
`allowsCellSelection`	`boolean`

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.

'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
`onColumnResize`	`( (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. *
`onColumnResizeStart`	`( (key: Key )) => void`	Callback for when onColumnResize has started.
`onColumnResizeEnd`	`() => 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.
`widths`	`Map<Key, number>`	Currently calculated widths for all columns.
`resizingColumn`	`Key \| null`	Key of the currently resizing column.
`tableState`	`TableState<T>`	A reference to the table state.