ListBox is used to select one or more values from a list of items.
import { ListBox } from 'primereact/listbox';
Listbox is used as a controlled component with value and onChange properties along with the options collection. There are two alternatives of how to define the options property; One way is providing a collection of SelectItem instances having label-value pairs whereas other way is providing an array of arbitrary objects along with the optionLabel and optionValue properties to specify the label/value field pair. In addition, options can be simple primitive values such as a string array, in this case no optionLabel or optionValue is necessary.
<ListBox value={selectedCity} options={cities} onChange={(e: ListBoxChangeParams) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
<ListBox multiple value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
Property name or getter function to use as the label of an option group.
<ListBox value={selectedGroupedCity} options={groupedCities} onChange={(e) => setSelectedGroupedCity(e.value)} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} style={{ width: '15rem' }} listStyle={{ maxHeight: '250px' }}/>
<ListBox filter value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
<ListBox value={selectedCountries} options={countries} onChange={(e) => setSelectedCountries(e.value)} optionLabel="name" itemTemplate={countryTemplate} style={{ width: '15rem' }} listStyle={{ maxHeight: '250px' }} />
<ListBox className='p-invalid' value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
<ListBox disabled value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
Whether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.
<ListBox value={selectedItem} options={items} virtualScrollerOptions={{ itemSize: 38 }} onChange={(e) => setSelectedItem(e.value)} style={{ width: '15rem' }} listStyle={{ height: '250px' }}/>
Formik is a popular library for handling forms in React.
<Toast ref={toast} />
<ListBox
id="item"
name="item"
value={formik.values.item}
options={cities}
optionLabel="name"
placeholder="Select a City"
onChange={(e) => {
formik.setFieldValue('item', e.value);
}}
style={{ width: '15rem' }}
/>
<Toast ref={toast} />
<Controller
name="value"
control={control}
rules={{ required: 'Value is required.' }}
render={({ field }) => <ListBox value={field.value} optionLabel="name" placeholder="Select a City" name="value" options={cities} control={control} onChange={(e) => field.onChange(e.value)} style={{ width: '15rem' }} />}
/>
Following is the list of structural style classes, for theming classes visit theming page.
Name | Element |
---|---|
p-listbox | Main container element. |
p-listbox-header | Header element. |
p-listbox-list-wrapper | Container of list element. |
p-listbox-list | List element. |
p-listbox-item | An item in the list element. |
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" />
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. |