- Components
- Menus and selection
- ListBox
ListBox
A list of options that can allow selection of one or more.
Installation
Usage
Use ListBox
to display a list of options and allow a user to select one or more of them.
ListBox Options
Orientation
By default, ListBox
expects items to be arranged in a vertical stack, and implements keyboard navigation and drag and drop accordingly.
Use the orientation
prop to change the layout to a horizontal stack.
Layout
The layout
prop can be set to "grid"
to enable two-dimensional keyboard navigation.
Selection mode
ListBox supports multiple selection modes. By default, selection is disabled, however this can be changed using the selectionMode
prop.
Selection behavior
When selectionBehavior
is set to "replace"
, clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl
, Cmd
, and Shift
can be used. On touch screen devices, selection always behaves as toggle since modifier keys may not be available.
Loading
Use the isLoading
prop to indicate that the list is loading.
Empty state
Use the renderEmptyState
prop to customize what the ListBox will display if there are no items.
Item options
Variant
Use the variant
prop to set the visual style of the item.
Label and description
By default, items in a ListBox are labeled by their text contents for accessibility. Items also support the "label"
and "description"
props to separate primary and secondary content.
Prefix and suffix
To add additional context for the item, such as icons, use the prefix
and suffix
props.
Link
Items may be links to another page or website. This can be achieved by passing the href
prop to the Item
component.
Disabled
An Item
can be disabled with the isDisabled
prop.
Sections
ListBox
supports sections in order to group options. Sections can be used by wrapping groups of items in a Section element.
Sections without a title
must provide an aria-label
for accessibility.
Separator
Separators may be added between items or sections in order to create non-labeled groupings.
Uncontrolled
Use defaultSelectedKey
to set a default selected item.
Controlled
Use selectedKey
and onChange
props to control the selected item.
Selected items: nextjs, remix, astro
Composition
If you need to customize things further, you can drop down to the composition level.
Examples
Asynchronous loading
This example uses the useAsyncList
hook to handle asynchronous loading of data from a server.
API Reference
ListBox
Prop | Type | Default | Description |
---|---|---|---|
selectionBehavior | 'toggle' | 'replace' | - | How multiple selection should behave in the collection. |
dragAndDropHooks | DragAndDropHooks | - | The drag and drop hooks returned by useDragAndDrop used to enable drag and drop behavior for the ListBox. |
renderEmptyState | (props: ListBoxRenderProps) => ReactNode | - | Provides content to display when there are no items in the list. |
layout | 'stack' | 'grid' | 'stack' | Whether the items are arranged in a stack or grid. |
orientation | 'horizontal' | 'vertical' | 'vertical' | The primary orientation of the items. Usually this is the direction that the collection scrolls. |
autoFocus | boolean | 'first' | 'last' | - | 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. |
selectionMode | 'none' | 'single' | 'multiple' | - | 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). |
children | ReactNode | (item: object) => ReactNode | - | The contents of the collection. |
dependencies | any[] | - | Values that should invalidate the item cache when using dynamic collections. |
className | string | (values: ListBoxRenderProps & {defaultClassName: string | undefined}) => string | - | The CSS className for the element. A function may be provided to compute the class based on component state. |
style | CSSProperties | (values: ListBoxRenderProps & {defaultStyle: CSSProperties}) => CSSProperties | - | The inline style for the element. A function may be provided to compute the style based on component state. |
Event | Type | Description |
---|---|---|
onAction | (key: Key) => void | Handler that is called when an item is selected. |
onSelectionChange | (keys: Selection) => void | Handler that is called when the selection changes. |
onFocus | (e: FocusEvent<Target>) => void | Handler that is called when the element receives focus. |
onBlur | (e: FocusEvent<Target>) => 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. |
onScroll | (e: UIEvent<Element>) => void | Handler that is called when a user scrolls. |
Item
Prop | Type | Default | Description |
---|---|---|---|
id | Key | - | The unique id of the item. |
variant | 'default' | 'success' | 'warning' | 'danger' | 'accent' | "default" | The visual style of the menu item. |
value | object | - | The object value that this item represents. When using dynamic collections, this is set automatically. |
textValue | string | - | A string representation of the item's contents, used for features like typeahead. |
isDisabled | boolean | - | Whether the item is disabled. |
children | ReactNode | (values: ListBoxItemRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
className | string | - | The CSS className for the element. |
style | CSSProperties | (values: ListBoxItemRenderProps & {defaultStyle: CSSProperties}) => CSSProperties | - | The inline style for the element. A function may be provided to compute the style based on component state. |
href | Href | - | A URL to link to. |
hrefLang | string | - | Hints at the human language of the linked URL. |
target | HTMLAttributeAnchorTarget | - | The target window for the link. |
rel | string | - | The relationship between the linked resource and the current page. |
download | boolean | string | - | Causes the browser to download the linked URL. A string may be provided to suggest a file name. |
ping | string | - | A space-separated list of URLs to ping when the link is followed. |
referrerPolicy | HTMLAttributeReferrerPolicy | - | How much of the referrer to send when following the link. |
routerOptions | RouterOptions | - | Options for the configured client side router. |
Event | Type | Description |
---|---|---|
onAction | () => void | Handler that is called when the item is selected. |
onHoverStart | (e: HoverEvent) => void | Handler that is called when a hover interaction starts. |
onHoverEnd | (e: HoverEvent) => void | Handler that is called when a hover interaction ends. |
onHoverChange | (isHovering: boolean) => void | Handler that is called when the hover state changes. |
Accessibility
Keyboard interactions
Key | Description |
---|---|
Tab | Focuses the first item. |
ArrowDown | When focus is on an item, moves focus to the next item. |
ArrowUp | When focus is on an item, moves focus to the previous item. |