MultiSelect

MultiSelect is used to select multiple items from a collection.


import { MultiSelect } from 'primereact/multiselect';
         

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

Select a City

<MultiSelect value={selectedCities1} options={cities} onChange={(e) => setSelectedCities1(e.value)} optionLabel="name" placeholder="Select a City" maxSelectedLabels={3} />
         

Used mode to display the selected items as chips.

Select a City

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

A floating label is implemented by wrapping the input and the label inside a container having .p-float-label style class.

empty

<span className="p-float-label">
    <MultiSelect inputId="multiselect" value={selectedCities} options={cities} onChange={(e) => setSelectedCities(e.value)} optionLabel="name" maxSelectedLabels={3} />
    <label htmlFor="multiselect">Select a City</label>
</span>         

Applying p-invalid class to an input element indicates a failed validation.

empty

<MultiSelect className="p-invalid" value={selectedCities1} options={cities} onChange={(e) => setSelectedCities1(e.value)} optionLabel="name" maxSelectedLabels={3} />
         

disabled prop prevents an input from being editable.

Select a City

<MultiSelect disabled placeholder="Select a City" />
         

Used mode to display the selected items as chips.

Select Cities

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

Template of the panel header.

Select Countries

<MultiSelect value={selectedCountries} options={countries} onChange={(e) => setSelectedCountries(e.value)} optionLabel="name" placeholder="Select Countries" className="multiselect-custom" itemTemplate={countryTemplate} selectedItemTemplate={selectedCountriesTemplate} panelFooterTemplate={panelFooterTemplate} />
         

Select a City

<MultiSelect filter value={selectedCities1} options={cities} onChange={(e) => setSelectedCities1(e.value)} optionLabel="name" placeholder="Select a City" maxSelectedLabels={3} />
         
Section Content

Whether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.

Select Item

<MultiSelect value={selectedItems} options={items} onChange={(e) => {setSelectedItems(e.value); setSelectAll(e.value.length === items.length)}} selectAll={selectAll} onSelectAll={(e) => {setSelectedItems(e.checked ? [] : items.map(item => item.value)); setSelectAll(!e.checked)}} virtualScrollerOptions={{ itemSize: 43 }} maxSelectedLabels={3} placeholder="Select Item"/>
         

Whether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.

Select Item

<MultiSelect value={selectedItems} options={lazyItems} onChange={(e) => setSelectedItems(e.value)} virtualScrollerOptions={{ lazy: true, onLazyLoad: onLazyLoad, itemSize: 43, showLoader: true, loading: lazyLoading, delay: 250, loadingTemplate: (options) => {
    return (
        <div className="flex align-items-center p-2" style={{ height: '43px' }}>
            <Skeleton width={options.even ? '70%' : '60%'} height="1.5rem" />
        </div>
    )}
}} maxSelectedLabels={3} placeholder="Select Item" showSelectAll={false}/>
         
Compatibility with popular React form libraries.

Formik is a popular library for handling forms in React.

Select a City
 

<Toast ref={toast} />
<MultiSelect id="item" name="item" options={cities} value={formik.values.item} onChange={(e) => { formik.setFieldValue('item', e.value) }} optionLabel="name" placeholder="Select a City" maxSelectedLabels={3} />
<Button type="submit" label="Submit" className="mt-2" />
         

Select a City
 

<Toast ref={toast} />
<Controller
    name="value"
    control={control}
    rules={{ required: 'Value is required.' }}
    render={({ field }) => <MultiSelect id={field.name} name="value" value={field.value} options={cities} onChange={(e) => field.onChange(e.value)} optionLabel="name" placeholder="Select a City" maxSelectedLabels={3} />}
/>
<Button type="submit" label="Submit" className="mt-2" />
         

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

NameElement
p-multiselectContainer element.
p-multiselect-label-containerContainer of the label to display selected items.
p-multiselect-label-containerLabel to display selected items.
p-multiselect-triggerDropdown button.
p-multiselect-filter-containerContainer of filter input.
p-multiselect-panelOverlay panel for items.
p-multiselect-itemsList container of items.
p-multiselect-itemAn item in the list.
p-multiselect-tokenA selected item element container on display='chip' mode.
p-chips-token-iconIcon of a selected item element on display='chip' mode.
p-chips-token-labelLabel of a selected item element on display='chip' mode.
Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Screen Reader

Value to describe the component can either be provided with aria-labelledby or aria-label props. The multiselect component has a combobox role in addition to aria-haspopup and aria-expanded attributes. The relation between the combobox and the popup is created with aria-controls attribute that refers to the id of the popup listbox.

The popup listbox uses listbox as the role with aria-multiselectable enabled. Each list item has an option role along with aria-label, aria-selected and aria-disabled attributes.

Checkbox component at the header uses a hidden native checkbox element internally that is only visible to screen readers. Value to read is defined with the selectAll and unselectAll keys of the aria property from the locale API.

If filtering is enabled, filterInputProps can be defined to give aria-* props to the input element.

Close button uses close key of the aria property from the locale API as the aria-label by default, this can be overriden with the closeButtonProps.


<span id="dd1">Options</span>
<MultiSelect aria-labelledby="dd1" />

<MultiSelect aria-label="Options" />
 

Closed State Keyboard Support

KeyFunction
tabMoves focus to the multiselect element.
spaceOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.
down arrowOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.
up arrowOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.

Popup Keyboard Support

KeyFunction
tabMoves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus.
shift + tabMoves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus.
enterToggles the selection state of the focused option.
spaceToggles the selection state of the focused option.
escapeCloses the popup, moves focus to the multiselect element.
down arrowMoves focus to the next option, if there is none then visual focus does not change.
up arrowMoves focus to the previous option, if there is none then visual focus does not change.
homeMoves focus to the first option.
endMoves focus to the last option.
any printable characterMoves focus to the option whose label starts with the characters being typed if dropdown is not editable.

Toggle All Checkbox Keyboard Support

KeyFunction
spaceToggles the checked state.
escapeCloses the popup.

Filter Input Keyboard Support

KeyFunction
enterCloses the popup and moves focus to the multiselect element.
escapeCloses the popup and moves focus to the multiselect element.

Close Button Keyboard Support

KeyFunction
enterCloses the popup and moves focus to the multiselect element.
spaceCloses the popup and moves focus to the multiselect element.
escapeCloses the popup and moves focus to the multiselect element.
Visit the API documentation for detailed information about all the properties, events and methods of the component.