MultiSelect is used to select multiple items from a collection.
import { MultiSelectModule } from 'primeng/multiselect';
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.
<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" optionLabel="name"></p-multiSelect>
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">
<p-multiSelect [options]="cities" formControlName="selectedCities" optionLabel="name"></p-multiSelect>
</form>
Selected values are displayed as a comma separated list by default, setting display as chip displays them as chips.
<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" defaultLabel="Select a City" optionLabel="name" display="chip"></p-multiSelect>
Options can be grouped when a nested data structures is provided.
<p-multiSelect [options]="groupedCities" [group]="true" [(ngModel)]="selectedCities" defaultLabel="Select a City" scrollHeight="250px" display="chip">
<ng-template let-group pTemplate="group">
<div class="flex align-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>
Available options and the selected options support templating with pTemplate properties respectively. In addition, header, footer and filter sections can be templated as well.
<p-multiSelect [options]="countries" [(ngModel)]="selectedCountries" defaultLabel="Select a Country" optionLabel="name" >
<ng-template let-value pTemplate="selectedItems">
<div class="flex align-items-center gap-2" *ngFor="let option of selectedCountries1">
<img src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + option.code.toLowerCase()" style="width: 18px"/>
<div>{{ option.name }}</div>
</div>
<div *ngIf="!selectedCountries1 || selectedCountries1.length === 0">Select Countries</div>
</ng-template>
<ng-template let-country pTemplate="item">
<div class="flex align-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>
</p-multiSelect>
MultiSelect provides built-in filtering that is enabled by adding the filter property.
<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" [filter]="true" optionLabel="name"></p-multiSelect>
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.
<p-multiSelect [options]="virtualCountries" [showToggleAll]="false" [(ngModel)]="selectedCountries" optionLabel="name" [virtualScroll]="true" [filter]="true" [virtualScrollItemSize]="43" class="multiselect-custom-virtual-scroll">
<ng-template let-country pTemplate="item">
<div class="flex align-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>
</p-multiSelect>
A floating label appears on top of the input field when focused.
<span class="p-float-label">
<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" optionLabel="name"></p-multiSelect>
<label for="ms-cities">Select Cities</label>
</span>
Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.
<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" class="ng-dirty ng-invalid" optionLabel="name"></p-multiSelect>
When disabled is present, the element cannot be edited and focused.
<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" [disabled]="true" optionLabel="name"></p-multiSelect>
Following is the list of structural style classes, for theming classes visit theming page.
Name | Element |
---|---|
p-multiselect | Container element. |
p-multiselect-label-container | Container of the label to display selected items. |
p-multiselect-label | Label to display selected items. |
p-multiselect-trigger | Dropdown button. |
p-multiselect-filter-container | Container of filter input. |
p-multiselect-panel | Overlay panel for items. |
p-multiselect-items | List container of items. |
p-multiselect-item | An item in the list. |
p-multiselect-open | Container element when overlay is visible. |
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>
<p-multiSelect aria-labelledby="dd1"></p-multiSelect>
<p-multiSelect aria-label="Options"></p-multiSelect>
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. |
API defines helper props, events and others for the PrimeNG MultiSelect module.
Name | Type | Default | Description |
---|---|---|---|
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). |
ariaFilterLabel | string | null | Defines a string that labels the filter input. |
label | string | null | Label of the input for accessibility. |
ariaLabelledBy | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
autofocusFilter | boolean | false | Applies focus to the filter element when the overlay is shown. |
autoZIndex | boolean | true | Whether to automatically manage layering. |
baseZIndex | number | 0 | Base zIndex value to use in layering. |
defaultLabel | string | Choose | Label to display when there are no selections. Deprecated: Use placeholder instead. |
dataKey | string | null | A property to uniquely identify a value in options. |
disabled | boolean | false | When present, it specifies that the element should be disabled. |
displaySelectedLabel | boolean | true | Whether to show labels of selected item labels or use default label. |
dropdownIcon | string | null | Icon class of the dropdown icon. |
emptyFilterMessage | string | No results found | Text to display when filtering does not return any results. |
filter | boolean | true | When specified, displays an input field to filter the items on keyup. |
filterMatchMode | string | contains | Defines how the items are filtered, valid values are "contains" (default) "startsWith", "endsWith", "equals", "notEquals", "in", "lt", "lte", "gt" and "gte". |
filterValue | string | null | When specified, filter displays with this value. |
filterLocale | string | undefined | Locale to use in filtering. The default locale is the host environment's current locale. |
filterBy | string | null | When filtering is enabled, filterBy decides which field or fields (comma separated) to search against. |
filterPlaceHolder | string | null | Defines placeholder of the filter input. |
hideTransitionOptions | string | .1s linear | Transition options of the hide animation. |
inputId | string | null | Identifier of the focus input to match a label defined for the component. |
maxSelectedLabels | number | 3 | Decides how many selected item labels to show at most. |
name | string | null | Name of the input element. |
options | array | null | An array of objects to display as the available options. |
optionLabel | string | label | Name of the label field of an option. |
optionValue | string | value | Name of the value field of an option. |
optionDisabled | string | disabled | 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. |
group | boolean | false | Whether to display options as grouped when nested options are provided. |
overlayVisible | boolean | false | Specifies the visibility of the options panel. |
panelStyle | object | null | Inline style of the overlay panel. |
placeholder | string | null | Label to display when there are no selections. |
readonly | boolean | false | When present, it specifies that the component cannot be edited. |
emptyMessage | string | No records found. | Text to display when there is no data. Defaults to global value in i18n translation configuration. |
emptyFilterMessage | string | No results found | Text to display when filtering does not return any results. Defaults to global value in i18n translation configuration. |
resetFilterOnHide | boolean | false | Clears the filter value when hiding the dropdown. |
scrollHeight | string | 200px | Height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value. |
selectedItemsLabel | string | ellipsis | Label to display after exceeding max selected labels e.g. ({0} items selected), defaults "ellipsis" keyword to indicate a text-overflow. |
selectionLimit | number | null | Number of maximum options that can be selected. |
showHeader | boolean | true | Whether to show the header. |
showTransitionOptions | string | .12s cubic-bezier(0, 0, 0.2, 1) | Transition options of the show animation. |
showToggleAll | boolean | true | Whether to show the checkbox at header to toggle all items at once. |
style | object | null | Inline style of the element. |
panelStyle | string | null | Inline style of the overlay panel element. |
styleClass | string | null | Style class of the element. |
panelStyleClass | string | null | Style class of the overlay panel element. |
tabindex | number | null | Index of the element in tabbing order. |
tooltip | any | null | Advisory information to display in a tooltip on hover. |
tooltipStyleClass | string | null | Style class of the tooltip. |
tooltipPosition | string | top | Position of the tooltip, valid values are right, left, top and bottom. |
tooltipPositionStyle | string | absolute | Type of CSS position. |
showClear | boolean | false | When enabled, a clear icon is displayed to clear the value. |
virtualScroll | boolean | false | Whether the data should be loaded on demand during scroll. |
virtualScrollItemSize | number | null | Height of an item in the list for VirtualScrolling. |
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. |
lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
Name | Parameters | Description |
---|---|---|
onClick | event.originalEvent: Browser click event event.option: selected option event.selected: selected value | Callback to invoke when component is clicked. |
onChange | event.originalEvent: browser event event.value: Current selected values event.itemValue: Toggled item value | Callback to invoke when value changes. |
onFilter | event.originalEvent: Browser event event.filter: Filter value used in filtering. | Callback to invoke when data is filtered. |
onFocus | event.originalEvent: browser event | Callback to invoke when multiselect receives focus. |
onBlur | event.originalEvent: browser event | Callback to invoke when multiselect loses focus. |
onPanelShow | - | Callback to invoke when overlay panel becomes visible. |
onPanelHide | - | Callback to invoke when overlay panel becomes hidden. |
onClear | - | Callback to invoke when input field is cleared. |
onLazyLoad | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke in lazy mode to load new data. |
onRemove | event: MultiselectOnRemoveEvent | Callback to invoke in lazy mode to load new data. |
Name | Parameters |
---|---|
item | $implicit: Data of the item |
group | $implicit: Data of the group item |
selectedItems | $implicit: value |
header | - |
filter | options.filter: Callback to filter data by the value param options.reset: Resets the filter. |
empty | - |
emptyfilter | - |
footer | - |
loader | options: Options of the scroller on loading. *This template can be used with virtualScroll. |
checkicon | - |
filtericon | - |
removetokenicon | - |
closeicon | - |
clearicon | - |
dropdownicon | - |