DropdownDropdown is used to select an item from a collection of options. Custom content support and filtering are the notable features.

Documentation

CDK

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

npm install @angular/cdk --save
 

Import

import {DropdownModule} from 'primeng/dropdown';
 

Getting Started

Dropdown 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-dropdown [options]="cities1" [(ngModel)]="selectedCity1"></p-dropdown>
<p-dropdown [options]="cities2" [(ngModel)]="selectedCity2" optionLabel="name"></p-dropdown>
 

import {SelectItem} from 'primeng/api';
interface City {
  name: string;
  code: string;
}
export class MyModel {
    cities1: SelectItem[];
    cities2: City[];
    selectedCity1: City;
    selectedCity2: City;
    constructor() {
        //SelectItem API with label-value pairs
        this.cities1 = [
            {label:'Select City', value:null},
            {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

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

<p-dropdown [options]="cities" formControlName="selectedCity"></p-dropdown>
 

Filtering

Options can be filtered using an input field in the overlay by enabling the filter property. By default filtering is done against label of the SelectItem and filterBy property is available to choose one or more properties of the SelectItem API.

<p-dropdown [options]="cities" [(ngModel)]="selectedCity" [filter]="true"></p-dropdown>
<p-dropdown [options]="cities" [(ngModel)]="selectedCity" [filter]="true" filterBy="label,value.name"></p-dropdown>
 

Grouping

Displaying options as grouped is enabled by providing a collection of SelectItemGroup instances and setting group property to true.

<p-dropdown [options]="groupedCars" [(ngModel)]="selectedCar" placeholder="Select a Car" [group]="true"></p-dropdown>
 

import {SelectItem} from 'primeng/api';
import {SelectItemGroup} from 'primeng/api';
export class GroupDemo {
    selectedCar: string;
    groupedCars: SelectItemGroup[];
    constructor() {
        this.groupedCars = [
            {
                label: 'Germany', 
                items: [
                    {label: 'Audi', value: 'Audi'},
                    {label: 'BMW', value: 'BMW'},
                    {label: 'Mercedes', value: 'Mercedes'}
                ]
            },
            {
                label: 'USA', 
                items: [
                    {label: 'Cadillac', value: 'Cadillac'},
                    {label: 'Ford', value: 'Ford'},
                    {label: 'GMC', value: 'GMC'}
                ]
            },
            {
                label: 'Japan', 
                items: [
                    {label: 'Honda', value: 'Honda'},
                    {label: 'Mazda', value: 'Mazda'},
                    {label: 'Toyota', value: 'Toyota'}
                ]
            }
        ];
    }
}
 

Disabled Options

Particular options can be prevented from selection using the disabled property of SelectItem API.

Custom Content

Both the selected option and the options list can be templated to provide customization on the default behavior which is displaying label property of an option. Use "selectedItem" template to customize the selected label display and the "item" template to change the content of the options in the dropdown panel. 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. If the options are custom objects not SelectItem instances, use value property to access the custom object.

<p-dropdown [options]="cars" [(ngModel)]="selectedCar" [style]="{'width':'150px'}">
     <ng-template let-item pTemplate="selectedItem"> 
        <img src="assets/showcase/images/demo/car/{{item.label}}.png" style="width:16px;vertical-align:middle" /> 
        <span style="vertical-align:middle">{{item.label}}</span>
    </ng-template> 
    <ng-template let-car pTemplate="item"> 
        <div class="ui-helper-clearfix" style="position: relative;height:25px;">
        <img src="assets/showcase/images/demo/car/{{car.label}}.png" style="width:24px;position:absolute;top:1px;left:5px"/> 
        <div style="font-size:14px;float:right;margin-top:4px">{{car.label}}</div> </div>
    </ng-template>
</p-dropdown>
 

import {SelectItem} from 'primeng/api';
export class MyModel {
    cars: SelectItem[];
    selectedCar: 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'},
        ];
    }
}
 

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-dropdown [options]="cities" [virtualScroll]="true" itemSize="30"></p-dropdown>
 

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-dropdown [options]="cars" [(ngModel)]="selectedCar" [showTransitionOptions]="'0ms'" [hideTransitionOptions]="'0ms'"></p-dropdown>
 

Properties

Events

Methods

<p-dropdown #dd [options]="cars" [(ngModel)]="selectedCar" filter="true"></p-dropdown>
<button type="button" pButton label="Clear" (click)="clearFilter(dd)"></button>
 

clearFilter(dropdown: Dropdown) {
    dropdown.resetFilter();
}
 

Styling

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

Dependencies

None.

Source

View on GitHub

<h3 class="first">Single</h3>
<p-dropdown [options]="cities" [(ngModel)]="selectedCity" placeholder="Select a City" optionLabel="name" [showClear]="true"></p-dropdown>
<p>Selected City: {{selectedCity ? selectedCity.name : 'none'}}</p>
<h3>Editable</h3>
<p-dropdown [options]="cars" [(ngModel)]="selectedCar1" editable="true" placeholder="Select a Brand"></p-dropdown>
<p>Selected Car: {{selectedCar1 || 'none'}}</p>
<h3>Content with Filters</h3>
<p-dropdown [options]="cars" [(ngModel)]="selectedCar2" filter="true">
    <ng-template let-item pTemplate="selectedItem">
        <img src="assets/showcase/images/demo/car/{{item.label}}.png" style="width:16px;vertical-align:middle" />
        <span style="vertical-align:middle; margin-left: .5em">{{item.label}}</span>
    </ng-template>
    <ng-template let-car pTemplate="item">
        <div class="ui-helper-clearfix" style="position: relative;height: 25px;">
            <img src="assets/showcase/images/demo/car/{{car.label}}.png" style="width:24px;position:absolute;top:1px;left:5px"/>
            <div style="font-size:14px;float:right;margin-top:4px">{{car.label}}</div>
        </div>
    </ng-template>
</p-dropdown>
<p>Selected Car: {{selectedCar2 || 'none'}}</p>
<h3>Group</h3>
<p-dropdown [options]="groupedCars" [(ngModel)]="selectedCar3" placeholder="Select a Car" [group]="true">
    <ng-template let-group pTemplate="group">
        <img src="assets/showcase/images/demo/flag/{{group.value}}" style="width:20px;vertical-align:middle" />
        <span style="margin-left:.25em">{{group.label}}</span>
    </ng-template>
</p-dropdown>
<p>Selected Car: {{selectedCar3 || 'none'}}</p>
<h3>Virtual Scroll (10000 Items)</h3>
<p-dropdown [options]="items" [(ngModel)]="item" placeholder="Select Item" [virtualScroll]="true" [itemSize]="31" [filter]="false"></p-dropdown>
 

export class DropdownDemo {
    cities: City[];
    selectedCity: City;
    cars: SelectItem[];
    selectedCar1: string;
    selectedCar2: string = 'BMW';
    selectedCar3: string;
    groupedCars: SelectItemGroup[];
    items: SelectItem[];
    item: 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'}
        ];
        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'}
        ];
        this.groupedCars = [
            {
                label: 'Germany', value: 'germany.png', 
                items: [
                    {label: 'Audi', value: 'Audi'},
                    {label: 'BMW', value: 'BMW'},
                    {label: 'Mercedes', value: 'Mercedes'}
                ]
            },
            {
                label: 'USA', value: 'usa.png', 
                items: [
                    {label: 'Cadillac', value: 'Cadillac'},
                    {label: 'Ford', value: 'Ford'},
                    {label: 'GMC', value: 'GMC'}
                ]
            },
            {
                label: 'Japan', value: 'japan.png', 
                items: [
                    {label: 'Honda', value: 'Honda'},
                    {label: 'Mazda', value: 'Mazda'},
                    {label: 'Toyota', value: 'Toyota'}
                ]
            }
        ];
        this.items = [];
        for (let i = 0; i < 10000; i++) {
            this.items.push({label: 'Item ' + i, value: 'Item ' + i});
        }
    }
}