React MultiSelect

React MultiSelect is used to select multiple items from a collection.

Setup

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

Import

import { MultiSelect } from 'primereact/multiselect';

Getting Started

MultiSelect 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'}
];

<MultiSelect value={cities} options={citySelectItems} onChange={(e) => setCities(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'}
];

<MultiSelect optionLabel="name" value={cities} options={cities} onChange={(e) => setCities(e.value)} />
<MultiSelect optionLabel="name" optionValue="code" value={cities} options={cities} onChange={(e) => setCities(e.value)} />

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

Chips Display

A comma separated list is used by default to display selected items whereas alternative chip mode is provided using the display property to visualize the items as tokens.

<MultiSelect display="chip" optionLabel="name" value={selectedCities} options={cities} onChange={(e) => setSelectedCities(e.value)} />

Custom Content

Label of an option is used as the display text of an item by default, for custom content support define an itemTemplate function that gets the option as a parameter and returns the content.

<MultiSelect value={cities} options={citySelectItems} onChange={(e) => setCities(e.value)} itemTemplate={itemTemplate} />

itemTemplate(option) {
    // custom item content
}

In addition selectedItemTemplate can be used to customize the selected values display instead of the default comma separated list.

<MultiSelect value={cities} options={citySelectItems} onChange={(e) => setCities(e.value)} selectedItemTemplate={selectedItemTemplate} />

selectedItemTemplate(option) {
    // custom selected 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".

<MultiSelect value={cities} options={citySelectItems} onChange={(e) => setCities(e.value)} filter/>

Theming

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

Resources

Visit the PrimeReact MultiSelect showcase for demos and documentation.