File: multiselect.md | Updated: 11/15/2025
Introducing PrimeReact v11 Alpha 🥁Learn More
SearchK
10.9.7
FEATURES
API
THEMING
PASS THROUGH
MultiSelect is used to select multiple items from a collection.
Import#
import { MultiSelect } from 'primereact/multiselect';
Copy
Basic#
MultiSelect is used as a controlled component with value and onChange properties along with an options collection. Label and value of an option are defined with the optionLabel and optionValue properties respectively. Default property name for the optionLabel is label and value for the optionValue. If optionValue is omitted and the object has no value property, the object itself becomes the value of an option. Note that, when options are simple primitive values such as a string array, no optionLabel and optionValue would be necessary.
Select Cities
<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name"
placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />
Copy
Chips#
Selected values are displayed as a comma separated list by default, setting display as chip displays them as chips.
Select Cities
<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" display="chip"
placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />
Copy
Group#
Options can be grouped when a nested data structures is provided. To define the label of a group optionGroupLabel property is needed and also optionGroupChildren is required to define the property that refers to the children of a group.
Select Cities
<MultiSelect value={selectedCities} options={groupedCities} onChange={(e) => setSelectedCities(e.value)} optionLabel="label"
optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate}
placeholder="Select Cities" display="chip" className="w-full md:w-20rem" />
Copy
Template#
Available options and the selected options support templating with itemTemplate and selectedItemTemplate properties respectively. In addition, header, footer and filter sections can be templated as well.
Select Countries
<MultiSelect value={selectedCountries} options={countries} onChange={(e) => setSelectedCountries(e.value)} optionLabel="name"
placeholder="Select Countries" itemTemplate={countryTemplate} panelFooterTemplate={panelFooterTemplate} className="w-full md:w-20rem" display="chip" />
Copy
Filter#
MultiSelect provides built-in filtering that is enabled by adding the filter property.
Select Cities
<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name"
filter placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />
Copy
Loading State#
Loading state can be used loading property.
Loading...
<MultiSelect loading placeholder="Loading..." className="w-full md:w-20rem" />
Copy
Virtual Scroll#
VirtualScroller is used to render a long list of options efficiently like 100K records in this demo. The configuration is done with virtualScrollerOptions property, refer to the VirtualScroller for more information about the available options as it is used internally by MultiSelect.
Select Items
<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 Items"
className="w-full md:w-20rem"
/>
Copy
Float Label#
A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.
empty
MultiSelect
<FloatLabel>
<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" maxSelectedLabels={3} className="w-full" />
<label htmlFor="ms-cities">MultiSelect</label>
</FloatLabel>
Copy
Filled#
Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.
Select Cities
<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name"
placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />
Copy
Invalid#
Invalid state is displayed using the invalid prop to indicate a failed validation. You can use this style when integrating with form validation libraries.
Select Cities
<MultiSelect invalid value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name"
placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />
Copy
Disabled#
When disabled is present, the element cannot be edited and focused.
Select Cities
<MultiSelect disabled placeholder="Select Cities" className="w-full md:w-20rem" />
Copy
Accessibility#
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" />
Copy
| Key | Function | | --- | --- | | tab | Moves focus to the multiselect element. | | space | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. | | down arrow | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. | | up arrow | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
| Key | Function | | --- | --- | | tab | Moves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus. | | shift + tab | Moves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus. | | enter | Toggles the selection state of the focused option. | | space | Toggles the selection state of the focused option. | | escape | Closes the popup, moves focus to the multiselect element. | | down arrow | Moves focus to the next option, if there is none then visual focus does not change. | | up arrow | Moves focus to the previous option, if there is none then visual focus does not change. | | home | Moves focus to the first option. | | end | Moves focus to the last option. | | any printable character | Moves focus to the option whose label starts with the characters being typed if dropdown is not editable. |
| Key | Function | | --- | --- | | space | Toggles the checked state. | | escape | Closes the popup. |
| Key | Function | | --- | --- | | enter | Closes the popup and moves focus to the multiselect element. | | escape | Closes the popup and moves focus to the multiselect element. |
| Key | Function | | --- | --- | | enter | Closes the popup and moves focus to the multiselect element. | | space | Closes the popup and moves focus to the multiselect element. | | escape | Closes the popup and moves focus to the multiselect element. |
Import
Basic
Chips
Group
Template
Filter
Loading State
Virtual Scroll
Float Label
Filled
Invalid
Disabled
Accessibility
PrimeReact 10.9.7 by PrimeTek