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

NameTypeDescription
sizenumberThe number of items in the collection.

Methods

MethodDescription
getKeys(): Iterable<Key>Iterate over all keys in the collection.
getItem( (key: Key )): TnullGet an item by its key.
at( (idx: number )): TnullGet an item by the index of its key.
getKeyBefore( (key: Key )): KeynullGet the key that comes before the given key in the collection.
getKeyAfter( (key: Key )): KeynullGet the key that comes after the given key in the collection.
getFirstKey(): KeynullGet the first key in the collection.
getLastKey(): KeynullGet the last key in the collection.
getChildren( (key: Key )): Iterable<T>Iterate over the child items of the given key.
getTextValue( (key: Key )): stringReturns 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#


NameTypeDescription
typestringThe type of item this node represents.
keyKeyA unique key for the node.
valueTnullThe object value the node was created from.
levelnumberThe level of depth this node is at in the hierarchy.
hasChildNodesbooleanWhether this item has children, even if not loaded yet.
renderedReactNodeThe rendered contents of this node (e.g. JSX).
textValuestringA string value for this node, used for features like typeahead.
aria-labelstringAn accessibility label for this node.
indexnumberThe index of this node within its parent.
wrapper( (element: ReactElement )) => ReactElementA function that should be called to wrap the rendered node.
parentKeyKeynullThe key of the parent node.
prevKeyKeynullThe key of the node before this node.
nextKeyKeynullThe key of the node after this node.
propsanyAdditional properties specific to a particular node type.
render( (node: Node<any> )) => ReactElementA function that renders this node to a React Element in the DOM.