React ListBox

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

Setup

Refer to PrimeReact setup documentation for download and installation steps for your environment.

Import

import { ListBox } from 'primereact/listbox';

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 true by default. On touch enabled devices metaKeySelection is turned off automatically.

<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.

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

itemTemplate(option) {
    // custom item content
}

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 />

Theming

ListBox supports various themes featuring Material, Bootstrap, Fluent as well as your own custom themes via the Designer tool.

Resources

Visit the PrimeReact ListBox showcase for demos and documentation.