MultiSelect MultiSelect is used to select multiple items from a collection.

Basic

Selected Cars: {{selectedCars1}}

Template

{{car.label}}

Selected Cars: {{selectedCars2}}

Import


import {MultiSelectModule} from 'primeng/multiselect';

Getting Started

MultiSelect requires a value to bind and a collection of options. There are two alternatives of how to define the options property; one way is providing a collection of SelectItem instances whereas other way is providing an array of arbitrary objects along with the optionLabel property to specify the field name of the option. SelectItem API is designed to have more control on how the options are displayed such as grouping and disabling however in most cases an arbitrary object collection will suffice. Example below demonstrates both cases.


<p-multiSelect [options]="cities1" [(ngModel)]="selectedCities1"></p-multiSelect>

<p-multiSelect [options]="cities2" [(ngModel)]="selectedCities2" optionLabel="name"></p-multiSelect>



import {SelectItem} from 'primeng/api';

interface City {{
    name: string,
    code: string
}}

export class MyModel {

    cities1: SelectItem[];
    
    cities2: City[];

    selectedCities1: City[];
    
    selectedCities2: City[];

    constructor() {
        //SelectItem API with label-value pairs
        this.cities1 = [
            {label:'New York', value:{id:1, name: 'New York', code: 'NY'}},
            {label:'Rome', value:{id:2, name: 'Rome', code: 'RM'}},
            {label:'London', value:{id:3, name: 'London', code: 'LDN'}},
            {label:'Istanbul', value:{id:4, name: 'Istanbul', code: 'IST'}}
            {label:'Paris', value:{id:5, name: 'Paris', code: 'PRS'}}
        ];
        
        //An array of cities
        this.cities2 = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
    }

}

Model Driven Forms

MultiSelect can be used in a model driven form as well.


<p-multiSelect [options]="cities" formControlName="selectedCities"></p-multiSelect>

Templating

Label of a selectitem is displayed by default next to the checkbox in the overlay panel and it is possible to customize the content using templating. The ngTemplate receives the selectitem as the implicit variable along with the index of the option.


<p-multiSelect [options]="cars" [(ngModel)]="selectedCars2" [panelStyle]="{minWidth:'12em'}">
    <ng-template let-car let-i="index" pTemplate="item">
        {{i}}
        <img src="assets/showcase/images/demo/car/{{car.label}}.png" style="width:24px;display:inline-block;vertical-align:middle"/>
        <div style="font-size:14px;float:right;margin-top:4px">{{car.label}}</div>
    </ng-template>
</p-multiSelect>
<p>Selected Cars: {{selectedCars2}}</p>

Properties

Name Type Default Description
options array null An array of objects to display as the available options.
optionLabel string null Name of the label field of an option when an arbitrary objects instead of SelectItems are used as options.
disabled boolean false When present, it specifies that the element should be disabled.
filter boolean true When specified, displays an input field to filter the items on keyup.
filterPlaceHolder string null Defines placeholder of the filter input.
defaultLabel string Choose Label to display when there are no selections.
appendTo any null Target element to attach the overlay, valid values are "body" or a local ng-template variable of another element.
style object null Inline style of the element.
styleClass string null Style class of the element.
panelStyle object null Inline style of the overlay panel.
styleClass string null Style class of the overlay panel.
scrollHeight string 200px Height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value.
overlayVisible boolean false Specifies the visibility of the options panel.
tabindex number null Index of the element in tabbing order.
dataKey string null A property to uniquely identify a value in options.
inputId string null Identifier of the focus input to match a label defined for the component.
displaySelectedLabel boolean true Whether to show labels of selected item labels or use default label.
maxSelectedLabels number 3 Decides how many selected item labels to show at most.
selectedItemsLabel string {0} items selected Label to display after exceeding max selected labels.
showToggleAll boolean true Whether to show the checkbox at header to toggle all items at once.
resetFilterOnHide boolean false Clears the filter value when hiding the dropdown.
dropdownIcon string fa fa-fw fa-caret-down Icon class of the dropdown icon.

Events

Name Parameters Description
onChange event.originalEvent: browser event
event.value: Current selected values
event.itemValue: Toggled item value 		Callback to invoke when value changes.
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.

Styling

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

Name Element
ui-multiselect Container element.
ui-multiselect-label-container Container of the label to display selected items.
ui-multiselect-label-container Label to display selected items.
ui-multiselect-trigger Dropdown button.
ui-multiselect-filter-container Container of filter input.
ui-multiselect-panel Overlay panel for items.
ui-multiselect-items List container of items.
ui-multiselect-item An item in the list.

Dependencies

None.

 View on GitHub 

<h3 class="first">Basic</h3>
<p-multiSelect [options]="cars" [(ngModel)]="selectedCars1" [panelStyle]="{minWidth:'12em'}"></p-multiSelect>
<p>Selected Cars: {{selectedCars1}}</p>

<h3>Template</h3>
<p-multiSelect [options]="cars" [(ngModel)]="selectedCars2" [panelStyle]="{minWidth:'12em'}">
    <ng-template let-car pTemplate="item">
        <img src="assets/showcase/images/demo/car/{{car.label}}.png" style="width:24px;display:inline-block;vertical-align:middle"/>
        <div style="font-size:14px;float:right;margin-top:4px">{{car.label}}</div>
    </ng-template>
</p-multiSelect>
<p>Selected Cars: {{selectedCars2}}</p>



export class MultiSelectDemo {

    cars: SelectItem[];

    selectedCars1: string[] = [];

    selectedCars2: string[] = [];

    constructor() {
        this.cars = [
            {label: 'Audi', value: 'Audi'},
            {label: 'BMW', value: 'BMW'},
            {label: 'Fiat', value: 'Fiat'},
            {label: 'Ford', value: 'Ford'},
            {label: 'Honda', value: 'Honda'},
            {label: 'Jaguar', value: 'Jaguar'},
            {label: 'Mercedes', value: 'Mercedes'},
            {label: 'Renault', value: 'Renault'},
            {label: 'VW', value: 'VW'},
            {label: 'Volvo', value: 'Volvo'}
        ];
    }
}