useListBox

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.

Example

ListBox.tsx

ListBox.css

Example

ListBox.tsx

ListBox.css

import {ListBox, ListBoxItem} from './ListBox';

<ListBox aria-label="Alignment" selectionMode="single">
  <ListBoxItem id="left">Left</ListBoxItem>
  <ListBoxItem id="middle">Middle</ListBoxItem>
  <ListBoxItem id="right">Right</ListBoxItem>
</ListBox>

API

<ListBox>
  <ListBoxItem>
    <Text slot="label" />
    <Text slot="description" />
    <SelectionIndicator />
  </ListBoxItem>
  <ListBoxSection>
    <Header />
    <ListBoxItem />
  </ListBoxSection>
  <ListBoxLoadMoreItem />
</ListBox>

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

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

useOption<T>(
  props: AriaOptionProps,
state: ListState<T>,
ref: RefObject<FocusableElement | null>
): OptionAria

useListBoxSection(props: AriaListBoxSectionProps): ListBoxSectionAria

ListState

Name	Type
`collection`	`Collection<Node<T>>`
A collection of items in the list.
`selectionManager`	`SelectionManager`
A selection manager to read and update multiple selection state.

`disabledKeys`	`Set<Key>`
A set of items that are disabled.

AriaListBoxOptions

Name	Type	Default
`isVirtualized`	`boolean`	Default: —
Whether the listbox uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	Default: —
An optional keyboard delegate implementation for type to select, to override the default.
`layoutDelegate`	`LayoutDelegate`	Default: —
A delegate object that provides layout information for items in the collection. By default this uses the DOM, but this can be overridden to implement things like virtualized scrolling.
`shouldUseVirtualFocus`	`boolean`	Default: —
Whether the listbox items should use virtual focus instead of being focused directly.
`linkBehavior`	`'action' \| 'selection' \| 'override'`	Default: `'override'`
The behavior of links in the collection. - 'action': link behaves like onAction. - 'selection': link follows selection interactions (e.g. if URL drives selection). - 'override': links override all other interactions (link items are not selectable).
`orientation`	`Orientation`	Default: `'vertical'`
The primary orientation of the items. Usually this is the direction that the collection scrolls.

`items`	`Iterable<T>`	Default: —
Item objects in the collection.

`selectionMode`	`SelectionMode`	Default: —
The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	Default: —
How multiple selection should behave in the collection.
`selectedKeys`	`'all' \| Iterable<Key>`	Default: —
The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	Default: —
The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`(keys: Selection) => void`	Default: —
Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	Default: —
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`	Default: —
Whether the collection allows empty selection.
`shouldSelectOnPressUp`	`boolean`	Default: —
Whether selection should occur on press up instead of press down.
`shouldFocusWrap`	`boolean`	Default: —
Whether focus should wrap around when the end/start is reached.
`shouldFocusOnHover`	`boolean`	Default: —
Whether options should be focused when the user hovers over them.
`escapeKeyBehavior`	`'clearSelection' \| 'none'`	Default: `'clearSelection'`
Whether pressing the escape key should clear selection in the listbox or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.

ListBoxAria

Name	Type
`labelProps`	`DOMAttributes`
Props for the listbox's visual label element (if any).
`listBoxProps`	`DOMAttributes`
Props for the listbox element.

AriaOptionProps

Name	Type
`key`	`Key`
The unique key for the option.

OptionAria

Name	Type
`hasAction`	`boolean`
Whether the item has an action, dependent on `onAction`, `disabledKeys`, and `disabledBehavior`. It may also change depending on the current selection state of the list (e.g. when selection is primary). This can be used to enable or disable hover styles or other visual indications of interactivity.
`allowsSelection`	`boolean`
Whether the item may be selected, dependent on `selectionMode`, `disabledKeys`, and `disabledBehavior`.
`isDisabled`	`boolean`
Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`isSelected`	`boolean`
Whether the item is currently selected.
`isPressed`	`boolean`
Whether the item is currently in a pressed state.
`isFocusVisible`	`boolean`
Whether the option is keyboard focused.
`isFocused`	`boolean`
Whether the option is currently focused.
`descriptionProps`	`DOMAttributes`
Props for the description text element inside the option, if any.
`labelProps`	`DOMAttributes`
Props for the main text element inside the option.
`optionProps`	`DOMAttributes`
Props for the option element.

AriaListBoxSectionProps

Name	Type
`heading`	`ReactNode`
The heading for the section.

ListBoxSectionAria

Name	Type
`groupProps`	`DOMAttributes`
Props for the group element.
`headingProps`	`DOMAttributes`
Props for the heading element, if any.
`itemProps`	`DOMAttributes`
Props for the wrapper list item.