ListBox

Import via Module

import { ListBox } from 'primereact/listbox';
 

Import via CDN

<script src="https://unpkg.com/primereact/core/core.min.js"></script>
<script src="https://unpkg.com/primereact/listbox/listbox.min.js"></script>
 

Getting Started

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.

Options as SelectItems

const citySelectItems = [
    {label: 'New York', value: 'NY'},
    {label: 'Rome', value: 'RM'},
    {label: 'London', value: 'LDN'},
    {label: 'Istanbul', value: 'IST'},
    {label: 'Paris', value: 'PRS'}
];
 

<ListBox value={city} options={citySelectItems} onChange={(e) => setCity(e.value)} />
 

Options as any type

const cities = [
    {name: 'New York', code: 'NY'},
    {name: 'Rome', code: 'RM'},
    {name: 'London', code: 'LDN'},
    {name: 'Istanbul', code: 'IST'},
    {name: 'Paris', code: 'PRS'}
];
 

<ListBox optionLabel="name" value={city} options={cities} onChange={(e) => setCity(e.value)} />
<ListBox optionLabel="name" optionValue="code" value={city} options={cities} onChange={(e) => setCity(e.value)} />
 

When optionValue is not defined, value of an option refers to the option object itself.

Selection

Listbox allows selection of either single or multiple items. In single case, model should be a single object reference whereas in multiple case should be an array. Multiple items can either be selected using metaKey or toggled individually depending on the value of metaKeySelection property value which is false by default. On touch enabled devices metaKeySelection is turned on automatically even when enabled.

<ListBox value={cities} options={cities} onChange={(e) => setCity(e.value)} multiple />
 

Custom Content

Label of an option is used as the display text of an item by default, for custom content support define an itemTemplate property. Its value can be JSXElement, function or string. For custom filter support, define a filterTemplate function that gets the option instance as a parameter and returns the content for the filter element.

<ListBox value={city} options={cities} onChange={(e) => setCity(e.value)} itemTemplate={itemTemplate} filter filterTemplate={filterTemplate}/>
 

const [filterValue, setFilterValue] = useState('');
const filterInputRef = React.useRef();

itemTemplate(option) {
    // custom item content
}

const filterTemplate = (options) => {
    let {filterOptions} = options;

    return (
        <div className="flex flex-column gap-2">
            <InputText value={filterValue} ref={filterInputRef} onChange={(e) => myFilterFunction(e, filterOptions)} />
            <Button label="Reset" onClick={() => myResetFunction(filterOptions)} />
        </div>
    )
}

const myResetFunction = (options) => {
    setFilterValue('');
    options.reset();
    filterInputRef && filterInputRef.current.focus()
}

const myFilterFunction = (event, options) => {
    let _filterValue = event.target.value;
    setFilterValue(_filterValue);
    options.filter(event);
}
 

Filtering

Options can be filtered using an input field in the overlay by enabling the filter property. By default filtering is done against label of the items and filterBy property is available to choose one or more properties of the options. In addition filterMatchMode can be utilized to define the filtering algorithm, valid options are "contains" (default), "startsWith", "endsWith", "equals" and "notEquals". Also, the filterValue and onFilterValueChange properties can be used to control the filter value.

<ListBox value={city} options={cities} onChange={(e) => setCity(e.value)} filter />
 

Filter input can be customized with the filterInputProps option that passes any property to the filter input element.

<ListBox value={city} options={cities} onChange={(e) => setCity(e.value)} filter filterInputProps={{className:'p-3', maxLength: 10}}/>
 

Grouping

Options groups are specified with the optionGroupLabel and optionGroupChildren properties.

const groupedCities = [
    {
        label: 'Germany', code: 'DE',
        items: [
            { label: 'Berlin', value: 'Berlin' },
            { label: 'Frankfurt', value: 'Frankfurt' },
            { label: 'Hamburg', value: 'Hamburg' },
            { label: 'Munich', value: 'Munich' }
        ]
    },
    {
        label: 'USA', code: 'US',
        items: [
            { label: 'Chicago', value: 'Chicago' },
            { label: 'Los Angeles', value: 'Los Angeles' },
            { label: 'New York', value: 'New York' },
            { label: 'San Francisco', value: 'San Francisco' }
        ]
    },
    {
        label: 'Japan', code: 'JP',
        items: [
            { label: 'Kyoto', value: 'Kyoto' },
            { label: 'Osaka', value: 'Osaka' },
            { label: 'Tokyo', value: 'Tokyo' },
            { label: 'Yokohama', value: 'Yokohama' }
        ]
    }
];
 

<ListBox value={selectedGroupedCity} options={groupedCities} onChange={(e) => setSelectedGroupedCity(e.value)} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" />
 

SelectItem API

Properties

Events

Styling

Following is the list of structural style classes, for theming classes visit theming page.

Accessibility

This section is under development. After the necessary tests and improvements are made, it will be shared with the users as soon as possible.

Dependencies

None.