Collection interface

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

Introduction#

The

Collection

interface provides a generic representation for many types of collections. The collection is read only (immutable), and sequential (ordered). Each item has a unique key that identifies it, which can be used to access items. It's like a combination of an array and a map: you can iterate over items in a well defined order, and also access items by key.

Interface#

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

Building a collection#

The

Collection

interface can be implemented in many ways. For example, you could write a class to expose the required methods and properties for an underlying data structure like an array or Map.

As discussed on the Collection Components page, React Spectrum implements a JSX-based API for defining collections. This is implemented by the

useCollection

hook. useCollection iterates over the JSX tree, and recursively builds a collection of Node objects. Each node includes the value of the item it represents, along with some metadata about its place in the collection.

These nodes are then wrapped in a class that implements the

Collection

interface, and exposes the nodes. State management hooks like useListState and useTreeState handle building the collection and exposing the necessary interface to components.

When implementing collection components using react-aria hooks like

useListBox

, and useSelect, you'll iterate over these nodes to render the data in the collection. The properties exposed by a node are described below.

Node interface#

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.

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

useCollection<T, C = Collection<Node<T>>>(
  props: CollectionBase<T>,
  factory: CollectionFactory<T, C>,
  context: unknown
): any

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`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.

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>

(
  (node: Iterable<Node<T>>,
  , prev: C
    |  | null
)) => C

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

Provides state management for list-like components. Handles building a collection of items from props, and manages multiple selection state.

useListState<T>(
  (props: ListProps<T>
)): ListState<T>

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`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.
`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.

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

Name	Type	Description
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

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.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.

Methods

Method	Description
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key )): 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.
`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.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.

Methods

Method	Description
`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 )): void`	Sets the focused key.

Provides state management for tree-like components. Handles building a collection of items from props, item expanded state, and manages multiple selection state.

useTreeState<T>(
  (props: TreeProps<T>
)): TreeState<T>

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`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.
`expandedKeys`	`Iterable<Key>`	The currently expanded keys in the collection (controlled).
`defaultExpandedKeys`	`Iterable<Key>`	The initial expanded keys in the collection (uncontrolled).
`onExpandedChange`	`( (keys: Set<Key> )) => any`	Handler that is called when items are expanded or collapsed.
`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.

Properties

Name	Type	Description
`collection`	`Collection<Node<T>>`	A collection of items in the tree.
`disabledKeys`	`Set<Key>`	A set of keys for items that are disabled.
`expandedKeys`	`Set<Key>`	A set of keys for items that are expanded.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

Methods

Method	Description
`toggleKey( (key: Key )): void`	Toggles the expanded state for an item by its key.

Provides the behavior and accessibility implementation for a listbox component. A listbox displays a list of options and allows a user to select one or more of them.

useListBox<T>(
  props: AriaListBoxOptions<T>,
  state: ListState<T>,
  ref: RefObject<HTMLElement>
): ListBoxAria

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`isVirtualized`	`boolean`	Whether the listbox uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	An optional keyboard delegate implementation for type to select, to override the default.
`label`	`ReactNode`	An optional visual label for the listbox.
`autoFocus`	`boolean \| FocusStrategy`	Whether to auto focus the listbox or an option.
`shouldFocusWrap`	`boolean`	Whether focus should wrap around when the end/start is reached.
`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.
`isLoading`	`boolean`	Whether the items are currently loading.
`onLoadMore`	`() => any`	Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.
`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.
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Method	Description
`getKeyBelow( (key: Key )): Key`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key: Key, , global: boolean )): Key`	Returns the first key, or `null` for none.
`getLastKey( (key: Key, , global: boolean )): Key`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey: Key )): Key`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

'first' | 'last'

Name	Type	Description
`listBoxProps`	`HTMLAttributes<HTMLElement>`	Props for the listbox element.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the listbox's visual label element (if any).

Provides the behavior and accessibility implementation for a select component. A select displays a collapsible list of options and allows a user to select one of them.

useSelect<T>(
  props: AriaSelectOptions<T>,
  state: SelectState<T>,
  ref: RefObject<HTMLElement>
): SelectAria

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`keyboardDelegate`	`KeyboardDelegate`	An optional keyboard delegate implementation for type to select, to override the default.
`isOpen`	`boolean`	Sets the open state of the menu
`defaultOpen`	`boolean`	Sets the default open state of the menu
`onOpenChange`	`( (isOpen: boolean )) => void`	Method that is called when the open state of the menu changes
`shouldFlip`	`boolean`	Whether the menu should automatically flip direction when space is limited
`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.
`isLoading`	`boolean`	Whether the items are currently loading.
`onLoadMore`	`() => any`	Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.
`isDisabled`	`boolean`	Whether the input is disabled.
`isReadOnly`	`boolean`	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`label`	`ReactNode`	The content to display as the label.
`placeholder`	`string`	Temporary text that occupies the text input when it is empty.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKey`	`Key`	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	The initial selected key in the collection (uncontrolled).
`onSelectionChange`	`( (key: Key )) => any`	Handler that is called when the selection changes.
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

'valid' | 'invalid'

Properties

Name	Type	Description
`selectedKey`	`Key`	The key for the currently selected item.
`selectedItem`	`Node<T>`	The value of the currently selected item.
`isFocused`	`boolean`	Whether the select is currently focused.
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.
`focusStrategy`	`FocusStrategy`	Controls which item will be auto focused when the menu opens.
`isOpen`	`boolean`	Whether the overlay is currently open.

Methods

Method	Description
`setSelectedKey( (key: Key )): void`	Sets the selected key.
`setFocused( (isFocused: boolean )): void`	Sets whether the select is focused.
`toggle( (focusStrategy: FocusStrategy \| \| null )): void`	Toggles the menu.
`open(): void`	Opens the overlay.
`close(): void`	Closes the overlay.

Name	Type	Description
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the label element.
`triggerProps`	`AriaButtonProps`	Props for the popup trigger element.
`valueProps`	`HTMLAttributes<HTMLElement>`	Props for the element representing the selected value.
`menuProps`	`HTMLAttributes<HTMLElement>`	Props for the popup.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`elementType`	`string \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`aria-expanded`	`boolean`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

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.

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

BaseEvent<ReactKeyboardEvent<any>>

T & {stopPropagation: () => void,
continuePropagation: () => void
}