Angular MultiSelect

Angular MultiSelect is used to multiple values from a list of options.

Setup

Refer to PrimeNG setup documentation for download and installation steps for your environment.

CDK

Virtual Scrolling enabled MultiSelect depends on @angular/cdk's ScrollingModule so begin with installing CDK if not already installed.

npm install @angular/cdk --save

Import

import {MultiSelectModule} from 'primeng/multiselect';

Getting Started

MultiSelect requires a value to bind and a collection of options.

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

interface City {
    name: string,
    code: string
}

export class MultiSelectDemo {

    cities: City[];

    selectedCities: City[];

    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
    }

}

Value Binding

The option itself is bound to the model by default, use optionValue to customize the property to pass as the value.

<p-multiSelect [options]="cities" [(ngModel)]="selectedCityCodes" optionLabel="name" optionValue="code"></p-multiSelect>

interface City {
    name: string,
    code: string
}

export class MultiSelectDemo {

    cities: City[];

    selectedCityCodes: string[];

    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
    }

}

Chips Display

A comma separated list is used by default to display selected items whereas alternative chip mode is provided using the display property to visualize the items as tokens.

<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" display="chip"></p-multiSelect>

Disabled Options

Particular options can be prevented from selection using the optionDisabled property.

<p-multiSelect [options]="cities" [(ngModel)]="selectedCities" optionLabel="name" optionDisabled="inactive"></p-multiSelect>

export class MultiSelectDemo {

    cities: City[];

    selectedCities: City[];

    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY', inactive: false},
            {name: 'Rome', code: 'RM', inactive: true},
            {name: 'London', code: 'LDN', inactive: false},
            {name: 'Istanbul', code: 'IST', inactive: true},
            {name: 'Paris', code: 'PRS', inactive: false}
        ];
    }

}

Model Driven Forms

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

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

Custom Content

For custom content support when displaying options, define a ng-template named item where the local ng-template variable refers to an option in the options collection. Similarly selectedItems template can be used to customize when displaying the selected options. Additionally a custom header and footer can be provided using header and footer templates. In addition when grouping is enabled, group template is available to customize the option groups. All templates get the option instance as the default local template variable.

<p-multiSelect [options]="countries" [(ngModel)]="selectedCountries" defaultLabel="Select a Country" optionLabel="name" class="multiselect-custom">
    <ng-template pTemplate="header">
        Header Content
    </ng-template>
    <ng-template let-value pTemplate="selectedItems">
        <div class="country-item country-item-value" *ngFor="let option of selectedCountries">
            <img src="assets/showcase/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + option.code.toLowerCase()" />
            <div>{{option.name}}</div>
        </div>
        <div *ngIf="!selectedCountries || selectedCountries.length === 0" class="country-placeholder">
            Select Countries
        </div>
    </ng-template>
    <ng-template let-country pTemplate="item">
        <div class="country-item">
            <img src="assets/showcase/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + country.code.toLowerCase()" />
            <div>{{country.name}}</div>
        </div>
    </ng-template>
    <ng-template pTemplate="footer">
        Footer Content
    </ng-template>
</p-multiSelect>

interface Country {
    name: string,
    code: string
}

export class MultiSelectDemo {

    countries: Country[];

    selectedCountries: Country[];

    constructor() {
        this.countries = [
            {name: 'Australia', code: 'AU'},
            {name: 'Brazil', code: 'BR'},
            {name: 'China', code: 'CN'},
            {name: 'Egypt', code: 'EG'},
            {name: 'France', code: 'FR'},
            {name: 'Germany', code: 'DE'},
            {name: 'India', code: 'IN'},
            {name: 'Japan', code: 'JP'},
            {name: 'Spain', code: 'ES'},
            {name: 'United States', code: 'US'}
        ];
    }

}

Virtual Scrolling

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 itemSize to specify the height of an item.

<p-multiSelect [options]="cities" formControlName="selectedCities" optionLabel="name" [virtualScroll]="true" itemSize="30"></p-multiSelect>

Animation Configuration

Transition of the open and hide animations can be customized using the showTransitionOptions and hideTransitionOptions properties, example below disables the animations altogether.

<p-multiSelect [options]="cities" formControlName="selectedCities" optionLabel="name" [showTransitionOptions]="'0ms'" [hideTransitionOptions]="'0ms'"></p-multiSelect>

Theming

MultiSelect supports various themes featuring Material, Bootstrap, Fluent as well as your own custom themes via the Designer tool.

Resources

Visit the PrimeNG MultiSelect showcase for demos and documentation.