Collection API

Examples

Basic Example

The ListBox on its own isn't very useful. It registers each item with the model. The ListBox.Item only uses the useListItemRegister hook which handles registration of static items to the model. The ListBox uses useListRenderItems which handles rendering static items as well as Dynamic List example).

Identifying Items

A list item takes an optional data-id property that will be used to identify an item. Without a data-id, the identifier will be the item's index when first registered. The basic example has a data-id attribute that is a string representation of the index. Providing a data-id will override to a value of your choosing. This identifier will be used by other hooks to identify the item for selection, maintaining a cursor, or anything else.

Dynamic Items

The ListBox also handles a dynamic collection of items. Instead of providing each ListBox.Item statically, provide a render function instead. The function is called with an items value that is the same was what's provided to the model. By default, providing items will enable virtualization. This example adds a maxHeight to ensure overflow. Virtualization uses absolute positioning of each item, which could cause problems for popup menus. If your item count is low, pass shouldVirtualize={false} to disable virtualization.

Roving Tabindex

The list system also includes a cursor that extends the list. A cursor is mostly used for focusing items. The roving tabindex is a well-supported way to accomplish accessibility requirements for focusing items within a list. This example shows how to use useListRovingFocus. This example uses the ListBox component, but the default ListBox.Item is very basic. We have two options, we can either pass additional functionality via elemPropsHook or by creating a new item using our elemProps hook primitives. Both will be demonstrated. Creating a custom item is recommended if you create a custom component and export it. Using elemPropsHook with ListBox.Item is recommended only for one-off instances.

You can either use the tab key for focus on an item or click on an item and then use the up/down keys to navigation the list. By default, the list is set to wrap navigation using the wrappingNavigationManager. Only a single item in the list is a focus stop that "roves" as the up/down arrows are pressed.

Note: This example doesn't meet accessibility requirements. The list will have to have some type of context. Like "navigation list" or "menu list".

Selection

Lists support selection. useSelectionItem is applied to an item which adds an onClick that adds the item to the state.selectedIds. The default selection manager is a single select. This example uses ListBox and creates a custom SelectableItem elemProps hook and component.

Multiple Selection

The selection manager can be passed directly to the model configuration to handle different selection types. This example passes the multiSelectionManager to handle selecting multiple items.

Basic Grid

A grid is a two dimensional list. A columnCount config is added to inform how to break up an array of items. A grid is very similar to a list - it receives items as a single dimension list and uses the columnCount to determine keyboard navigation. Grids only support a single orientation.

Wrapping Grid

By default, navigating a grid does not wrap around when the user reaches the end of a row or column. The grid model supports passing in a navigation manager. The collection system supports two types of navigation managers, a non-wrapping navigationManager and the wrappingNavigationManager. The following example passes the wrappingNavigationManager manager to the model. Observe how the cursor wraps around columns and rows when an edge of a column or row is encountered.

Component API

ListBox

const useMyItem = composeHooks(
  useListItemSelect, // additional hooks go here
  useListItemRegister // always last
);

const list = useListModel({
  // custom handling for selection. single and multi select are provided
  selection: mySelectionManager,
  // wrapping and non-wrapping navigation are provided
  navigation: myNavigationManager,
  items: [{ id: '1', text: 'First'}, { id: '2', text: 'Second' }],
  getId: item => item.id, // get the unique identifier of your item
})

Navigation Manager

navigationManager

The navigationManager implements the Navigation Manager interface for lists and grids, but does not wrap when the user hits a boundary of the collection. This is the default navigation manager for grids.

wrappingNavigationManager

The wrappingNavigationManager implements the Navigation Manager interface for lists and grids, and wraps when the user hits a boundary of the collection. Grids will wrap columns, but not rows. This is the default navigation manager for lists.

Selection Manager

Hooks

useListItemRegister

const useMyItem = composeHooks(
  useListItemSelect, // additional hooks go here
  useListItemRegister // always last
);

useListItemRovingFocus

const useMyItem = composeHooks(
  useListItemRovingFocus, // adds the roving tabindex support
  useListItemRegister
);

useListItemSelect

const useMyItem = composeHooks(
  useListItemSelect, // adds selection support to an item
  useListItemRegister
);

useListRenderItems

const MyList = createContainer('ul')({
  modelHook: useListModel,
})((elemProps, Element, model) => {
  return <Element {...elemProps}>{useListRenderItems(model, elemProps.children)}</Element>;
});

useListResetCursorOnBlur

const useMyItem = composeHooks(
  useListResetCursorOnBlur, // adds the cursor reset to selected for roving tabindex
  useListItemRovingFocus,
  useListItemRegister
);

useOverflowListItemMeasure

const useMyItem = composeHooks(
  useOverflowListItemMeasure,
  useListRegisterItem,
)

useOverflowListMeasure

useOverflowListTarget