MultiSelect
MultiSelect is used to select multiple items from a collection.
Usage #
Examples #
Basic #
MultiSelect is used as a controlled component with v-model property 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.
Chips #
Selected values are displayed as a comma separated list by default, setting display as chip displays them as chips.
Group #
Options can be grouped when a nested data structures is provided.
Template #
Available options and the selected options support customization with option and chip templates respectively. In addition, header, footer and filter sections can be templated as well.
Filter #
MultiSelect provides built-in filtering that is enabled by adding the filter property.
Loading State #
Loading state can be used loading property.
VirtualScroll #
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.
Float Label #
A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.
Ifta Label #
IftaLabel is used to create infield top aligned labels. Visit IftaLabel documentation for more information.
Clear Icon #
When showClear is enabled, a clear icon is displayed to clear the value.
Sizes #
MultiSelect provides small and large sizes as alternatives to the base.
Fluid #
The fluid prop makes the component take up the full width of its container when set to true.
Filled #
Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.
Disabled #
When disabled is present, the element cannot be edited and focused.
Invalid #
The invalid state is applied using the invalid property to indicate failed validation, which can be integrated with form validation libraries.
Forms #
MultiSelect integrates seamlessly with the PrimeVue Forms library.
Accessibility #
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, the filter input is labelled with filterPlaceholder when defined, otherwise the filter key of the aria property from the locale API is used.
Close button uses close key of the aria property from the locale API as the aria-label by default, this can be overridden with the closeButtonProps.
Closed State Keyboard Support
| 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. |
| enter | 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. |
| any printable character | Opens the popup and moves focus to the option whose label starts with the characters being typed, if there is none then first option receives the focus. |
Popup Keyboard Support
| 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, then moves focus to the multiselect element. |
| space | Toggles the selection state of the focused option, then moves focus to the multiselect element. |
| 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. |
| alt + up arrow | Selects the focused option and closes the popup, then moves focus to the multiselect element. |
| shift + down arrow | Moves focus to the next option and toggles the selection state. |
| shift + up arrow | Moves focus to the previous option and toggles the selection state. |
| shift + space | Selects the items between the most recently selected option and the focused option. |
| home | Moves focus to the first option. |
| end | Moves focus to the last option. |
| control + shift + home | Selects the focused options and all the options up to the first one. |
| control + shift + end | Selects the focused options and all the options down to the last one. |
| control + a | Selects all options. |
| pageUp | Jumps visual focus to first option. |
| pageDown | Jumps visual focus to last option. |
| any printable character | Moves focus to the option whose label starts with the characters being typed. |
Toggle All Checkbox Keyboard Support
| Key | Function |
|---|---|
| space | Toggles the checked state. |
| escape | Closes the popup and moves focus to the multiselect element. |
Filter Input Keyboard Support
| Key | Function |
|---|---|
| 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. |
| left arrow | Removes the visual focus from the current option and moves input cursor to one character left. |
| right arrow | Removes the visual focus from the current option and moves input cursor to one character right. |
| home | Moves input cursor at the end, if not then moves focus to the first option. |
| end | Moves input cursor at the beginning, if not then moves focus to the last option. |
| enter | Closes the popup and moves focus to the multiselect element. |
| escape | Closes the popup and moves focus to the multiselect element. |
| tab | Moves focus to the next focusable element in the popup. If there is none, the focusable option is selected and the overlay is closed then moves focus to next element in page. |