Skip to main content

Listbox

A <Listbox> represents a list of selectable options. Single or multiple options can be selected based on the situation.

Overview#

The <Listbox> component is visually similar to the native <select> element with a size attribute provided. Like the native element, it can be used to select a single option from a list or multiple.

For single options, selection follows the <select> behavior of not allowing deselection once an item is chosen, only switching to another item.

Multiple selections#

Add the multiple prop to allow toggling more than one item. In multiselect mode items default to toggling their selected state on click, or keyboard selection. Selected values are represented as an Array.

Complex data#

Like the dropdown components the <Listbox> can accept complex data items. Configure dataKey and textField to resolve values and display text to the correct places.

API#

data#

An array of possible values for the Listbox.

Tip: When data is an array of objects consider specifying textField and dataKey as well.

type: array

dataKey#

A property name that provides the value of the data items. This value is used to uniquely distinigush items from others in the data list.

Generally, dataKey points to an Id field, or other unique identifier. When not provided, the referential identity of each data item is used.

type: string(dataItem?) => string

disabled#

type: booleanArray

focusedItem#

type: any

messages#

Object hash containing display text and/or text for screen readers. Use the messages object to localize widget text or provide custom rendering.

type:

onHoverOption#

type: function

onMove#

type: function

onSelect#

This handler fires when an item has been selected from the list. It fires before the onChange handler and fires regardless of whether the value has actually changed.

type: function

optionComponent#

type: elementType

renderGroup#

type: function

renderItem#

type: function

searchTerm#

Controls the value of the search text used to filter undefined items. searchTerm is only applicable when filtering is enabled.

Use defaultSearchTerm instead to set an initial value for uncontrolled widgets.

type: string

selectedItem#

type: any

textField#

A property name, or accessor function, that provides the text content of the data items. The Listbox will filter data based on this value as well as use it as the default display value for list items and selected values.

type: string(dataItem?) => string