ListBox

A list box displays actions relevant to the user’s current selection.

Props

isFluid?

Whether or not the ListBox is 100% of its container's width.

isInvalid?

Whether or not the ListBox is in an invalid state.

isLoading?

Whether data is currently being loaded.

onLoadMore?

Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.

selectionIndicator?

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.

Defaults to check.
size?

A ListBox can vary in size.

Defaults to sm.
loadingListBoxItemProps?

The props of the ListBoxItem.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

children?

The contents of the collection.

selectionBehavior?

How multiple selection should behave in the collection.

autoFocus?

Whether to auto focus the listbox or an option.

shouldFocusWrap?

Whether focus should wrap around when the end/start is reached.

items?

Item objects in the collection.

disabledKeys?

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

selectionMode?

The type of selection that is allowed in the collection.

disallowEmptySelection?

Whether the collection allows empty selection.

selectedKeys?

The currently selected keys in the collection (controlled).

defaultSelectedKeys?

The initial selected keys in the collection (uncontrolled).

onSelectionChange?

Handler that is called when the selection changes.

id?

The element's unique identifier. See MDN.

dragAndDropHooks?

The drag and drop hooks returned by useDragAndDrop used to enable drag and drop behavior for the ListBox.

renderEmptyState?

Provides content to display when there are no items in the list.

layout?

Whether the items are arranged in a stack or grid.

Defaults to 'stack'.
orientation?

The primary orientation of the items. Usually this is the direction that the collection scrolls.

Defaults to 'vertical'.
dependencies?

Values that should invalidate the item cache when using dynamic collections.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

onScroll?

Handler that is called when a user scrolls. See MDN.

onFocus?

Handler that is called when the element receives focus.

onBlur?

Handler that is called when the element loses focus.

onFocusChange?

Handler that is called when the element's focus status changes.

onAction?

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.

aria-label?

Defines a string value that labels the current element.

aria-labelledby?

Identifies the element (or elements) that labels the current element.

aria-describedby?

Identifies the element (or elements) that describes the object.

aria-details?

Identifies the element (or elements) that provide a detailed, extended description for the object.

slot?

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.

ListBoxItem

isLoading?

Whether the item is loading.

size?

A ListBoxItem can vary in size.

Defaults to sm.
isInvalid?

Whether or not the ListBoxItem is in an invalid state.

selectionIndicator?

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.

Defaults to check.
radioProps?

The props for the Radio.

checkboxProps?

The props for the Checkbox.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

id?

The unique id of the item.

value?

The object value that this item represents. When using dynamic collections, this is set automatically.

textValue?

A string representation of the item's contents, used for features like typeahead.

aria-label?

An accessibility label for this item.

isDisabled?

Whether the item is disabled.

onAction?

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.

children?

The children of the component. A function may be provided to alter the children based on component state.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

href?

A URL to link to. See MDN.

hrefLang?

Hints at the human language of the linked URL. SeeMDN.

target?

The target window for the link. See MDN.

rel?

The relationship between the linked resource and the current page. See MDN.

download?

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping?

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy?

How much of the referrer to send when following the link. See MDN.

routerOptions?

Options for the configured client side router.

onHoverStart?

Handler that is called when a hover interaction starts.

onHoverEnd?

Handler that is called when a hover interaction ends.

onHoverChange?

Handler that is called when the hover state changes.

Anatomy

The Header component represents a header within a Hopper container.

Section

The Section component represents a section within a Hopper container.

Composed Components

ListBox

ListBoxItem

Examples

Empty state

A list box can have an empty state.

Disabled

A list box with a disabled item.

Invalid

A list box that is invalid.

Fluid

A fluid list box will take up the full width of its container.

Section

A list box can have sections and section headers.

Avatar

A ListBox can contain an avatar.

Count

A list box can contain a count using a badge.

Dynamic Lists

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.

Icons

A list box can contain icons.

End Icons

A list box can contain icons at the end of a list item.

Loading

A list box can have a loading state.

Load on scroll

A list box can load more items when scrolling within.

Single selection

A list box can have a single selected item.

Single selection indicator

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.

Multiple selection

A list box can have multiple selected items.

Sizes

List boxes can vary in size.

Description

A list box item can have a description.

Item size

List box items can vary in sizes.

Migration Notes

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.