MultiSelect

MultiSelect is used to select multiple items from a collection.

Import #


import { MultiSelectModule } from 'primeng/multiselect';

Basic #

MultiSelect is used as a controlled component with ngModel 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.

Select Cities


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" optionLabel="name" placeholder="Select Cities" [maxSelectedLabels]="3" styleClass="w-full md:w-80" />

Reactive Forms #

MultiSelect can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.


<form [formGroup]="formGroup" class="card flex justify-center">
    <p-multiselect [options]="cities" formControlName="selectedCities" optionLabel="name" placeholder="Select Cities" [maxSelectedLabels]="3" styleClass="w-full md:w-80" />
</form>

Chips #

Selected values are displayed as a comma separated list by default, setting display as chip displays them as chips.

Select Cities


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" placeholder="Select Cities" optionLabel="name" display="chip" styleClass="w-full md:w-80" />

Group #

Options can be grouped when a nested data structures is provided.

Select Cities


<p-multiselect [options]="groupedCities" [group]="true" [(ngModel)]="selectedCities" placeholder="Select Cities" scrollHeight="250px" display="chip" styleClass="w-full md:w-80">
    <ng-template let-group pTemplate="group">
        <div class="flex items-center">
            <img
                src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png"
                [class]="'mr-2 flag flag-' + group.value"
                style="width: 20px" />
            <span>{{ group.label }}</span>
        </div>
    </ng-template>
</p-multiselect>

Template #

Available options and the selected options support templating with pTemplate properties respectively. In addition, header, footer and filter sections can be templated as well.

Select Countries


<p-multiselect
    [options]="countries"
    [(ngModel)]="selectedCountries"
    placeholder="Select Countries"
    optionLabel="name"
    styleClass="w-full md:w-80"
    display="chip"
>
    <ng-template let-country pTemplate="item">
        <div class="flex items-center gap-2">
            <img
                src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png"
                [class]="'flag flag-' + country.code.toLowerCase()"
                style="width: 18px"
            />
            <div>{{ country.name }}</div>
        </div>
    </ng-template>
    <ng-template pTemplate="dropdownicon">
        <i class="pi pi-map"></i>
    </ng-template>
    <ng-template pTemplate="filtericon">
        <i class="pi pi-map-marker"></i>
    </ng-template>
    <ng-template pTemplate="header">
        <div class="font-medium px-3 py-2">Available Countries</div>
    </ng-template>
    <ng-template pTemplate="footer">
        <div class="p-3 flex justify-between">
            <p-button label="Add New" severity="secondary" text size="small" icon="pi pi-plus" />
            <p-button label="Remove All" severity="danger" text size="small" icon="pi pi-times" />
        </div>
    </ng-template>
</p-multiselect>

Filter #

MultiSelect provides built-in filtering that is enabled by adding the filter property.

Select Cities


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" [filter]="true" optionLabel="name" placeholder="Select Cities" [maxSelectedLabels]="3" styleClass="w-full md:w-80" />

Loading State #

Loading state can be used loading property.


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" [loading]="true" optionLabel="name" placeholder="Loading..." styleClass="w-full md:w-80" />

VirtualScroll #

VirtualScrolling is an efficient way of rendering the options by displaying a small subset of data in the viewport at any time. When dealing with huge number of options, it is suggested to enable VirtualScrolling to avoid performance issues. Usage is simple as setting virtualScroll property to true and defining virtualScrollItemSize to specify the height of an item.

Select Cities


<p-multiselect [options]="items" [showToggleAll]="true" [selectAll]="selectAll" [(ngModel)]="selectedItems" optionLabel="label" [virtualScroll]="true" [virtualScrollItemSize]="43" class="multiselect-custom-virtual-scroll" placeholder="Select Cities" (onSelectAllChange)="onSelectAllChange($event)" [maxSelectedLabels]="3" styleClass="w-full md:w-80" #ms>
    <ng-template #headercheckboxicon let-allSelected let-partialSelected="partialSelected">
        <i class="pi pi-check" *ngIf="allSelected"></i>
        <i class="pi pi-minus" *ngIf="partialSelected" [ngStyle]="{ color: 'var(--text-color)' }"></i>
    </ng-template>
</p-multiselect>

Float Label #

A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.

empty

Over Label

empty

In Label

empty

On Label


<p-floatlabel class="w-full md:w-80">
    <p-multiselect id="over_label" [(ngModel)]="value1" [options]="cities" optionLabel="name" filter [maxSelectedLabels]="3" styleClass="w-full" />
    <label for="over_label">Over Label</label>
</p-floatlabel>

<p-floatlabel class="w-full md:w-80" variant="in">
    <p-multiselect id="in_label" [(ngModel)]="value2" [options]="cities" optionLabel="name" filter [maxSelectedLabels]="3" styleClass="w-full" />
    <label for="in_label">In Label</label>
</p-floatlabel>

<p-floatlabel class="w-full md:w-80" variant="on">
    <p-multiselect id="on_label" [(ngModel)]="value3" [options]="cities" optionLabel="name" filter [maxSelectedLabels]="3" styleClass="w-full" />
    <label for="on_label">On Label</label>
</p-floatlabel>

Ifta Label #

IftaLabel is used to create infield top aligned labels. Visit IftaLabel documentation for more information.

empty

Cities


<p-iftalabel class="w-full md:w-80">
    <p-multiselect [(ngModel)]="selectedCities" inputId="ms_cities" [options]="cities" optionLabel="name" [filter]="true" [maxSelectedLabels]="3" styleClass="w-full" />
    <label for="ms_cities">Cities</label>
</p-iftalabel>

Sizes #

MultiSelect provides small and large sizes as alternatives to the base.

Small

Normal

Large


<p-multiselect [(ngModel)]="value1" [options]="cities" optionLabel="name" [maxSelectedLabels]="3" styleClass="w-full md:w-80" size="small" placeholder="Small" />
<p-multiselect [(ngModel)]="value2" [options]="cities" optionLabel="name" [maxSelectedLabels]="3" styleClass="w-full md:w-80" placeholder="Normal" />
<p-multiselect [(ngModel)]="value3" [options]="cities" optionLabel="name" [maxSelectedLabels]="3" styleClass="w-full md:w-80" size="large" placeholder="Large" />

Filled #

Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.

Select Cities


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" variant="filled" optionLabel="name" placeholder="Select Cities" [maxSelectedLabels]="3" styleClass="w-full md:w-80" />

Invalid #

Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.

Select Cities


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" class="ng-dirty ng-invalid" optionLabel="name" [maxSelectedLabels]="3" styleClass="w-full md:w-80" />

Disabled #

When disabled is present, the element cannot be edited and focused.

Select Cities


<p-multiselect [options]="cities" [(ngModel)]="selectedCities" [disabled]="true" optionLabel="name" styleClass="w-full md:w-80" />

Accessibility #

Screen Reader

Value to describe the component can either be provided with ariaLabelledBy or ariaLabel 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>
<p-multiselect ariaLabelledBy="dd1"/>

<p-multiselect ariaLabel="Options"/>

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

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

Toggle All Checkbox Keyboard Support

Key	Function
space	Toggles the checked state.
escape	Closes the popup.

Filter Input Keyboard Support

Key	Function
enter	Closes the popup and moves focus to the multiselect element.
escape	Closes the popup and moves focus to the multiselect element.

Close Button Keyboard Support

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.

name	type	default	description
id	string	null	Unique identifier of the component
ariaLabel	string	null	Defines a string that labels the input for accessibility.
style	Object	null	Inline style of the element.
styleClass	string	null	Style class of the element.
panelStyle	any	null	Inline style of the overlay panel.
panelStyleClass	string	null	Style class of the overlay panel element.
inputId	string	null	Identifier of the focus input to match a label defined for the component.
disabled	boolean	false	When present, it specifies that the element should be disabled.
fluid	boolean	false	Spans 100% width of the container when enabled.
readonly	boolean	false	When present, it specifies that the component cannot be edited.
group	boolean	false	Whether to display options as grouped when nested options are provided.
filter	boolean	true	When specified, displays an input field to filter the items on keyup.
filterPlaceHolder	string	null	Defines placeholder of the filter input.
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
overlayVisible	boolean	false	Specifies the visibility of the options panel.
tabindex	number	0	Index of the element in tabbing order.
variant	"outlined" \| "filled"	outlined	Specifies the input variant of the component.
appendTo	any	null	Target element to attach the overlay, valid values are "body" or a local ng-template variable of another element (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having #mydiv as variable name).
dataKey	string	null	A property to uniquely identify a value in options.
name	string	null	Name of the input element.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
displaySelectedLabel	boolean	null	Whether to show labels of selected item labels or use default label.
maxSelectedLabels	number	null	Decides how many selected item labels to show at most.
selectionLimit	number	null	Decides how many selected item labels to show at most.
selectedItemsLabel	string	null	Label to display after exceeding max selected labels e.g. ({0} items selected), defaults "ellipsis" keyword to indicate a text-overflow.
showToggleAll	boolean	true	Whether to show the checkbox at header to toggle all items at once.
emptyFilterMessage	string	null	Text to display when filtering does not return any results.
emptyMessage	string	null	Text to display when there is no data. Defaults to global value in i18n translation configuration.
resetFilterOnHide	boolean	false	Clears the filter value when hiding the dropdown.
dropdownIcon	string	null	Icon class of the dropdown icon.
chipIcon	string	null	Icon class of the chip icon.
optionLabel	string	null	Name of the label field of an option.
optionValue	string	null	Name of the value field of an option.
optionDisabled	string	null	Name of the disabled field of an option.
optionGroupLabel	string	label	Name of the label field of an option group.
optionGroupChildren	string	items	Name of the options field of an option group.
showHeader	boolean	true	Whether to show the header.
filterBy	string	null	When filtering is enabled, filterBy decides which field or fields (comma separated) to search against.
scrollHeight	string	200px	Height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value.
lazy	boolean	false	Defines if data is loaded and interacted with in lazy manner.
virtualScroll	boolean	false	Whether the data should be loaded on demand during scroll.
loading	boolean	false	Whether the multiselect is in loading state.
virtualScrollItemSize	number	null	Height of an item in the list for VirtualScrolling.
loadingIcon	string	null	Icon to display in loading state.
virtualScrollOptions	ScrollerOptions	null	Whether to use the scroller feature. The properties of scroller component can be used like an object in it.
overlayOptions	OverlayOptions	null	Whether to use overlay API feature. The properties of overlay API can be used like an object in it.
ariaFilterLabel	string	null	Defines a string that labels the filter input.
filterMatchMode	"gt" \| "lt" \| "in" \| "startsWith" \| "contains" \| "endsWith" \| "equals" \| "notEquals" \| "lte" \| "gte"	contains	Defines how the items are filtered.
tooltip	string	null	Advisory information to display in a tooltip on hover.
tooltipPosition	"right" \| "left" \| "top" \| "bottom"	right	Position of the tooltip.
tooltipPositionStyle	string	absolute	Type of CSS position.
tooltipStyleClass	string	null	Style class of the tooltip.
autofocusFilter	boolean	false	Applies focus to the filter element when the overlay is shown.
display	string	comma	Defines how the selected items are displayed.
autocomplete	string	off	Defines the autocomplete is active.
size	"small" \| "large"	null	Defines the size of the component.
showClear	boolean	false	When enabled, a clear icon is displayed to clear the value.
autofocus	boolean	false	When present, it specifies that the component should automatically get focus on load.
autoZIndex	boolean	null
baseZIndex	number	null
showTransitionOptions	string	null	Transition options of the show animation.
hideTransitionOptions	string	null	Transition options of the hide animation.
defaultLabel	string	null	Label to display when there are no selections.
placeholder	Signal<string>	null	Label to display when there are no selections.
options	any[]	null	An array of objects to display as the available options.
filterValue	string	null	When specified, filter displays with this value.
itemSize	number	null	Item size of item to be virtual scrolled.
selectAll	boolean	null	Whether all data is selected.
focusOnHover	boolean	true	Indicates whether to focus on options when hovering over them, defaults to optionLabel.
filterFields	any[]	null	Fields used when filtering the options, defaults to optionLabel.
selectOnFocus	boolean	false	Determines if the option will be selected on focus.
autoOptionFocus	boolean	false	Whether to focus on the first visible or selected element when the overlay panel is shown.

name	parameters	description
onChange	event : MultiSelectChangeEvent	Callback to invoke when value changes.
onFilter	event : MultiSelectFilterEvent	Callback to invoke when data is filtered.
onFocus	event : MultiSelectFocusEvent	Callback to invoke when multiselect receives focus.
onBlur	event : MultiSelectBlurEvent	Callback to invoke when multiselect loses focus.
onClick	event : Event	Callback to invoke when component is clicked.
onClear	value : void	Callback to invoke when input field is cleared.
onPanelShow	value : void	Callback to invoke when overlay panel becomes visible.
onPanelHide	value : void	Callback to invoke when overlay panel becomes hidden.
onLazyLoad	event : MultiSelectLazyLoadEvent	Callback to invoke in lazy mode to load new data.
onRemove	event : MultiSelectRemoveEvent	Callback to invoke in lazy mode to load new data.
onSelectAllChange	event : MultiSelectSelectAllChangeEvent	Callback to invoke when all data is selected.

name	parameters	description
updateModel	value : any event : any	Updates the model value.
show	isFocus : any	Displays the panel.
hide	isFocus : any	Hides the panel.

name	parameters	description
item	context : { $implicit: any, // Data of the option. }	Custom header template.
selectedItems	context : { $implicit: any, // Selected option value. removeChip: undefined, // Function to remove chip. }	Custom selected item template.
header		Custom header template.
filter	context : { options: MultiSelectFilterOptions, // Filter options. }	Custom filter template.
footer		Custom footer template.
emptyfilter		Custom empty filter template.
empty		Custom empty template.
group	context : { $implicit: any, // Data of the item. }	Custom group template.
loader	context : { options: ScrollerOptions, // Virtual scroller options. }	Custom loader template. This template can be used with virtualScroll.
dropdownicon		Custom dropdown trigger icon template.
clearicon		Custom clear icon template.
filtericon		Custom filter icon template.
checkicon		Custom check icon template.
headercheckboxicon	context : { $implicit: boolean, // Defines if all items are selected. partialSelected: boolean, // Defines if items are partially selected. }	Custom check icon template for the header checkbox.
itemcheckboxicon	context : { $implicit: boolean, // Selection status of the item. }	Custom check icon template for the item checkbox.
closeicon		Custom close icon template.
removetokenicon		Custom remove token icon template.

name	type	description
originalEvent	Event	Browser event.
value	any	Current selected values.
itemValue	any	Toggled item value.

name	type	description
first	number	Index of the first element in viewport.
last	number	Index of the last element in viewport.

name	type	description
newValue	object	Value after the item removed.
removed	MultiSelectItem	Removed value.

class	description
p-multiselect	Class name of the root element
p-multiselect-label-container	Class name of the label container element
p-multiselect-label	Class name of the label element
p-multiselect-chip-item	Class name of the chip item element
p-multiselect-chip	Class name of the chip element
p-multiselect-chip-icon	Class name of the chip icon element
p-multiselect-dropdown	Class name of the dropdown element
p-multiselect-loading-icon	Class name of the loading icon element
p-multiselect-dropdown-icon	Class name of the dropdown icon element
p-multiselect-overlay	Class name of the overlay element
p-multiselect-header	Class name of the header element
p-multiselect-filter-container	Class name of the filter container element
p-multiselect-filter	Class name of the filter element
p-multiselect-list-container	Class name of the list container element
p-multiselect-list	Class name of the list element
p-multiselect-option-group	Class name of the option group element
p-multiselect-option	Class name of the option element
p-multiselect-empty-message	Class name of the empty message element

token	variable	description
multiselect.background	--p-multiselect-background	Background of root
multiselect.disabled.background	--p-multiselect-disabled-background	Disabled background of root
multiselect.filled.background	--p-multiselect-filled-background	Filled background of root
multiselect.filled.hover.background	--p-multiselect-filled-hover-background	Filled hover background of root
multiselect.filled.focus.background	--p-multiselect-filled-focus-background	Filled focus background of root
multiselect.border.color	--p-multiselect-border-color	Border color of root
multiselect.hover.border.color	--p-multiselect-hover-border-color	Hover border color of root
multiselect.focus.border.color	--p-multiselect-focus-border-color	Focus border color of root
multiselect.invalid.border.color	--p-multiselect-invalid-border-color	Invalid border color of root
multiselect.color	--p-multiselect-color	Color of root
multiselect.disabled.color	--p-multiselect-disabled-color	Disabled color of root
multiselect.placeholder.color	--p-multiselect-placeholder-color	Placeholder color of root
multiselect.invalid.placeholder.color	--p-multiselect-invalid-placeholder-color	Invalid placeholder color of root
multiselect.shadow	--p-multiselect-shadow	Shadow of root
multiselect.padding.x	--p-multiselect-padding-x	Padding x of root
multiselect.padding.y	--p-multiselect-padding-y	Padding y of root
multiselect.border.radius	--p-multiselect-border-radius	Border radius of root
multiselect.focus.ring.width	--p-multiselect-focus-ring-width	Focus ring width of root
multiselect.focus.ring.style	--p-multiselect-focus-ring-style	Focus ring style of root
multiselect.focus.ring.color	--p-multiselect-focus-ring-color	Focus ring color of root
multiselect.focus.ring.offset	--p-multiselect-focus-ring-offset	Focus ring offset of root
multiselect.focus.ring.shadow	--p-multiselect-focus-ring-shadow	Focus ring shadow of root
multiselect.transition.duration	--p-multiselect-transition-duration	Transition duration of root
multiselect.sm.font.size	--p-multiselect-sm-font-size	Sm font size of root
multiselect.sm.padding.x	--p-multiselect-sm-padding-x	Sm padding x of root
multiselect.sm.padding.y	--p-multiselect-sm-padding-y	Sm padding y of root
multiselect.lg.font.size	--p-multiselect-lg-font-size	Lg font size of root
multiselect.lg.padding.x	--p-multiselect-lg-padding-x	Lg padding x of root
multiselect.lg.padding.y	--p-multiselect-lg-padding-y	Lg padding y of root
multiselect.dropdown.width	--p-multiselect-dropdown-width	Width of dropdown
multiselect.dropdown.color	--p-multiselect-dropdown-color	Color of dropdown
multiselect.overlay.background	--p-multiselect-overlay-background	Background of overlay
multiselect.overlay.border.color	--p-multiselect-overlay-border-color	Border color of overlay
multiselect.overlay.border.radius	--p-multiselect-overlay-border-radius	Border radius of overlay
multiselect.overlay.color	--p-multiselect-overlay-color	Color of overlay
multiselect.overlay.shadow	--p-multiselect-overlay-shadow	Shadow of overlay
multiselect.list.padding	--p-multiselect-list-padding	Padding of list
multiselect.list.gap	--p-multiselect-list-gap	Gap of list
multiselect.list.header.padding	--p-multiselect-list-header-padding	Header padding of list
multiselect.option.focus.background	--p-multiselect-option-focus-background	Focus background of option
multiselect.option.selected.background	--p-multiselect-option-selected-background	Selected background of option
multiselect.option.selected.focus.background	--p-multiselect-option-selected-focus-background	Selected focus background of option
multiselect.option.color	--p-multiselect-option-color	Color of option
multiselect.option.focus.color	--p-multiselect-option-focus-color	Focus color of option
multiselect.option.selected.color	--p-multiselect-option-selected-color	Selected color of option
multiselect.option.selected.focus.color	--p-multiselect-option-selected-focus-color	Selected focus color of option
multiselect.option.padding	--p-multiselect-option-padding	Padding of option
multiselect.option.border.radius	--p-multiselect-option-border-radius	Border radius of option
multiselect.option.gap	--p-multiselect-option-gap	Gap of option
multiselect.option.group.background	--p-multiselect-option-group-background	Background of option group
multiselect.option.group.color	--p-multiselect-option-group-color	Color of option group
multiselect.option.group.font.weight	--p-multiselect-option-group-font-weight	Font weight of option group
multiselect.option.group.padding	--p-multiselect-option-group-padding	Padding of option group
multiselect.clear.icon.color	--p-multiselect-clear-icon-color	Color of clear icon
multiselect.chip.border.radius	--p-multiselect-chip-border-radius	Border radius of chip
multiselect.empty.message.padding	--p-multiselect-empty-message-padding	Padding of empty message

MultiSelect

Import #

Basic #

Reactive Forms #

Chips #

Group #

Template #

Filter #

Loading State #

VirtualScroll #

Float Label #

Ifta Label #

Sizes #

Filled #

Invalid #

Disabled #

Accessibility #

Screen Reader

Closed State Keyboard Support

Popup Keyboard Support

Toggle All Checkbox Keyboard Support

Filter Input Keyboard Support

Close Button Keyboard Support

MultiSelect API

MultiSelect #

Properties #

Emitters #

Methods #

Templates #

Events #

MultiSelectChangeEvent #

MultiSelectSelectAllChangeEvent #

MultiSelectFilterEvent #

MultiSelectFocusEvent #

MultiSelectBlurEvent #

MultiSelectLazyLoadEvent #

MultiSelectRemoveEvent #

Interfaces #

MultiSelectFilterOptions #

MultiSelect Theming

CSS Classes #

MultiSelect Design Tokens #