A listbox is a list of interactive options that appears when users interact with an element or perform a specific action.
A listbox is a disclosure component that appear with a set of actions relevant to a specific control, interface area, data element or application view. Typically, this context is determined by the user's current selection prior to invoking the menu. Listbox can be opened from components such as Selects or Buttons.
Whether or not the ListBox is 100% of its container's width.
Whether or not the ListBox is in an invalid state.
Whether data is currently being loaded.
The selection indicator to use. Only available if the selection mode is not "none". When set to "input", the selection indicator will be either a radio or checkbox based on the selection mode.
A ListBox can vary in size.
The props of the ListBoxItem.
The inline style for the element. A function may be provided to compute the style based on component state.
The contents of the collection.
How multiple selection should behave in the collection.
Whether selection should occur on press up instead of press down.
Whether options should be focused when the user hovers over them.
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.
Whether to auto focus the listbox or an option.
Whether focus should wrap around when the end/start is reached.
Item objects in the collection.
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
The type of selection that is allowed in the collection.
Whether the collection allows empty selection.
The currently selected keys in the collection (controlled).
The initial selected keys in the collection (uncontrolled).
The drag and drop hooks returned by useDragAndDrop used to enable drag and drop behavior for the ListBox.
Provides content to display when there are no items in the list.
Whether the items are arranged in a stack or grid.
The primary orientation of the items. Usually this is the direction that the collection scrolls.
Values that should invalidate the item cache when using dynamic collections.
The CSS className for the element. A function may be provided to compute the class based on component state.
Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.
Handler that is called when a user performs an action on an item. The exact user event depends on
the collection's selectionBehavior prop and the interaction modality.
Handler that is called when the selection changes.
Handler that is called when the element receives focus.
Handler that is called when the element loses focus.
Handler that is called when the element's focus status changes.
A slot name for the component. Slots allow the component to receive props from a parent component.
An explicit null value indicates that the local props completely override all props received from a parent.
The element's unique identifier. See MDN.
Defines a string value that labels the current element.
Identifies the element (or elements) that labels the current element.
Identifies the element (or elements) that describes the object.
Identifies the element (or elements) that provide a detailed, extended description for the object.
The inline style for the element.
Static child items or a function to render children.
Item objects in the section.
The unique id of the section.
The object value that this section represents. When using dynamic collections, this is set automatically.
Values that should invalidate the item cache when using dynamic collections.
The CSS className for the element.
An accessibility label for the section.
Whether the item is loading.
A ListBoxItem can vary in size.
Whether or not the ListBoxItem is in an invalid state.
The selection indicator to use. Only available if the selection mode is not "none". When set to "input", the selection indicator will be an either a radio or checkbox based on the selection mode.
The props for the Radio.
The props for the Checkbox.
The inline style for the element. A function may be provided to compute the style based on component state.
The unique id of the item.
The object value that this item represents. When using dynamic collections, this is set automatically.
A string representation of the item's contents, used for features like typeahead.
Whether the item is disabled.
The children of the component. A function may be provided to alter the children based on component state.
The CSS className for the element. A function may be provided to compute the class based on component state.
A URL to link to. See MDN.
Hints at the human language of the linked URL. SeeMDN.
The target window for the link. See MDN.
The relationship between the linked resource and the current page. See MDN.
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
A space-separated list of URLs to ping when the link is followed. See MDN.
How much of the referrer to send when following the link. See MDN.
Options for the configured client side router.
Not recommended – use onPress instead. onClick is an alias for onPress
provided for compatibility with other libraries. onPress provides
additional event details for non-mouse interactions.
Handler that is called when a user performs an action on the item. The exact user event depends on
the collection's selectionBehavior prop and the interaction modality.
Handler that is called when a hover interaction starts.
Handler that is called when a hover interaction ends.
Handler that is called when the hover state changes.
Handler that is called when the press is released over the target.
Handler that is called when a press interaction starts.
Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
Handler that is called when the press state changes.
Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
An accessibility label for this item.
<ListBox> <Divider /> /* (Optional) A divider in the ListBox */ <ListBoxItem> /* (Optional) An item in the ListBox */ <Avatar /> /* (Optional) An avatar in the ListBoxItem */ <Text /> /* (Optional) Text is optional, but becomes required if any other elements are present */ <Text slot="description" /> /* (Optional) A description in the ListBoxItem */ <Icon /> /* (Optional) An icon in the ListBoxItem */ <IconList /> /* (Optional) A list of icons in the ListBoxItem */ <Badge /> /* (Optional) A badge in the ListBoxItem */ </ListBoxItem> <ListBoxSection> /* (Optional) A section in the ListBox */ <Header /> /* (Optional) A header in the ListBoxSection */ <ListBoxItem /> /* (Optional) An item in the ListBoxSection */ </ListBoxSection> </ListBox>
A ListBox uses the following components:
A list box can have an empty state.
A list box with a disabled item.
A list box that is invalid.
A fluid list box will take up the full width of its container.
A list box can have sections and section headers.
A list box can have dividers.
A ListBox can contain an avatar.
A list box can contain a count using a badge.
Items and sections can be populated from a hierarchial data structure.
If a section has a header, the Collection component can be used to render the child items.
A list box can contain icons.
A list box can contain icons at the end of a list item.
A list box can have a loading state.
A list box can load more items when scrolling within.
A list box can have a single selected item.
A list box can have a different selection indicator for single select.
By default, disallowEmptySelection is set to true when the selection indicator is a radio button.
A list box can have multiple selected items.
List boxes can vary in size.
By default, the listbox maintains a minimum width of 218px to prevent a narrow appearance. If the menu labels become longer, the listbox component can expand up to a maximum of 288px when triggered by a button, or to the total width of the Select field.
A list box item can have a description.
List box items can vary in sizes.
A listbox can be composed of:
Listboxes should:
Use Listbox to hide less frequently used or advanced options until users specifically need them. This keeps the interface clean and focused on essential elements.
Coming from Orbiter, you should be aware of the following changes:
disabled has been renamed to isDisabled.validationState has been removed. isInvalid should be used instead.tabbable has been removed.useVirtualFocus doesn't exist.Listbox has been renamed to ListBox to follow React Aria Components.