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