MultiSelect

Import via Module

import { MultiSelect } from 'primereact/multiselect';
 

Import via CDN

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

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 instance as a parameter and returns the content. For custom filter support define a filterTemplate function that gets the option instance as a parameter and returns the content for the filter element.

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

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

itemTemplate(option) {
    // custom item content
}

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

    return (
        <div className="flex 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);
}
 

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
}
 

In addition panelHeaderTemplate and panelFooterTemplate can be used to customize the header and footer of panel.

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

panelHeaderTemplate(options) {
    // options.className: Style class of the panel header.
    // options.checkboxElement: Default checkbox element created by the component.
    // options.checked: Whether the all checkbox is checked.
    // options.onChange: Change event of toggleable checkbox.
    // options.filterElement: Default filter element created by the component.
    // options.closeElement: Default close element created by the component.
    // options.closeElementClassName: Style class of the close container
    // options.closeIconClassName: Style class of the close icon
    // options.onCloseClick: Click event for the close icon.
    // options.element: Default element created by the component.
    // options.props: component props.
}

panelFooterTemplate(options) {
    // options.props: component props.
}
 

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

<MultiSelect value={selectedGroupedCities} options={groupedCities} onChange={(e) => setSelectedGroupedCities(e.value)} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" />
 

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

SelectItem API

Properties

Any valid attribute is passed to the root element implicitly, extended properties are as follows;

Events

Methods

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.