Source: https://primereact.org/listbox/

Introducing PrimeReact v11 Alpha 🥁Learn More

SearchK
10.9.7
FEATURES
API
THEMING
PASS THROUGH

ListBox

ListBox is used to select one or more values from a list of items.

Import#

import { ListBox } from 'primereact/listbox';

Copy

Basic#

ListBox is used as a controlled component with value and onChange properties along with an options collection. Label and value of an option are defined with the optionLabel and optionValue properties respectively. Default property name for the optionLabel is label and value for the optionValue. If optionValue is omitted and the object has no value property, the object itself becomes the value of an option. Note that, when options are simple primitive values such as a string array, no optionLabel and optionValue would be necessary.

New York
Rome
London
Istanbul
Paris

<ListBox value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

Copy

Multiple#

ListBox allows choosing a single item by default, enable multiple property to choose more than one. When the optional metaKeySelection is present, behavior is changed in a way that selecting a new item requires meta key to be present.

New York
Rome
London
Istanbul
Paris

<ListBox multiple value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

Copy

Group#

Options can be grouped when a nested data structures is provided. To define the label of a group optionGroupLabel property is needed and also optionGroupChildren is required to define the property that refers to the children of a group.

Germany
Berlin
Frankfurt
Hamburg
Munich
USA
Chicago
Los Angeles
New York
San Francisco
Japan
Kyoto
Osaka
Tokyo
Yokohama

<ListBox value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={groupedCities} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupTemplate} className="w-full md:w-14rem" listStyle={{ maxHeight: '250px' }} />

Copy

Filter#

ListBox provides built-in filtering that is enabled by adding the filter property.

New York
Rome
London
Istanbul
Paris

<ListBox filter value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

Copy

Template#

Custom content for an option is displayed with the itemTemplate property that takes an option as a parameter. Additional available templating sections are filterTemplate and optionGroupTemplate.

Australia
Brazil
China
Egypt
France
Germany
India
Japan
Spain
United States

<ListBox value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" itemTemplate={countryTemplate} className="w-full md:w-14rem" listStyle={{ maxHeight: '250px' }} />

Copy

Virtual Scroll#

VirtualScroller is used to render a long list of options efficiently like 100K records in this demo. The configuration is done with virtualScrollerOptions property, refer to the VirtualScroller for more information about the available options as it is used internally by ListBox.

<ListBox value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} 
    virtualScrollerOptions={{ itemSize: 38 }} className="w-full md:w-14rem" listStyle={{ height: '250px' }} />

Copy

Invalid#

Invalid state is displayed using the invalid prop to indicate a failed validation. You can use this style when integrating with form validation libraries.

New York
Rome
London
Istanbul
Paris

<ListBox invalid value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

Copy

Disabled#

When disabled is present, the element cannot be edited and focused.

New York
Rome
London
Istanbul
Paris
<ListBox disabled options={cities} optionLabel="name" className="w-full md:w-14rem" />

Copy

Accessibility#

Screen Reader

Value to describe the component can be provided aria-labelledby or aria-label props. The list element has a listbox role with the aria-multiselectable attribute that sets to true when multiple selection is enabled. Each list item has an option role with aria-selected and aria-disabled as their attributes.

If filtering is enabled, filterInputProps can be defined to give aria-* props to the input element. Alternatively filterPlaceholder is usually utilized by the screen readers as well.

<span id="lb">Options</span>
<ListBox aria-labelledby="lb" />

<ListBox aria-label="City" />

Copy

Keyboard Support

| Key | Function | | --- | --- | | tab | Moves focus to the first selected option, if there is none then first option receives the focus. | | up arrow | Moves focus to the previous option. | | down arrow | Moves focus to the next option. | | enter | Toggles the selected state of the focused option. | | space | Toggles the selected state of the focused option. | | home | Moves focus to the first option. | | end | Moves focus to the last option. | | shift + down arrow | Moves focus to the next option and toggles the selection state. | | shift + up arrow | Moves focus to the previous option and toggles the selection state. | | shift + space | Selects the items between the most recently selected option and the focused option. | | control + shift + home | Selects the focused options and all the options up to the first one. | | control + shift + end | Selects the focused options and all the options down to the last one. | | control + a | Selects all options. |

Import
Basic
Multiple
Group
Filter
Template
Virtual Scroll
Invalid
Disabled
Accessibility

PrimeReact 10.9.7 by PrimeTek