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: 'Toyota', value: 'Toyota'}
                ]
            }
        ];
    }
}

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.


<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'},
        ];
    }
}

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.
name	string	null	Name of the input element.
scrollHeight	string	200px	Height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value.
style	string	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.
filter	boolean	false	When specified, displays an input field to filter the items on keyup.
filterBy	string	null	When filtering is enabled, filterBy decides which field or fields (comma separated) to search against.
filterPlaceholder	string	null	Placeholder text to show when filter input is empty.
autoWidth	boolean	true	Calculates the width based on options width, set to false for custom width.
required	boolean	false	When present, it specifies that an input field must be filled out before submitting the form.
disabled	boolean	false	When present, it specifies that the component should be disabled.
editable	boolean	false	When present, custom value instead of predefined options can be entered using the editable input field.
appendTo	any	null	Target element to attach the overlay, valid values are "body" or a local ng-template variable of another element.
tabindex	number	null	Index of the element in tabbing order.
placeholder	string	null	Default text to display when no option is selected.
inputId	string	null	Identifier of the focus input to match a label defined for the dropdown.
dataKey	string	null	A property to uniquely identify a value in options.
lazy	boolean	true	When enabled, creates the dom for options when overlay panel gets visible.
autofocus	boolean	false	When present, it specifies that the component should automatically get focus on load.
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.
emptyFilterMessage	string	No results found	Text to display when filtering does not return any results.
autoDisplayFirst	boolean	true	Whether to display the first item as the label if no placeholder is defined and value is null.
group	boolean	false	Whether to display options as grouped when nested options are provided.

Events

Name	Parameters	Description
onChange	event.originalEvent: Browser event event.value: Selected option value	Callback to invoke when value of dropdown changes.
onFocus	event: Browser event	Callback to invoke when dropdown gets focus.
onBlur	event: Browser event	Callback to invoke when dropdown loses focus.

Methods

Name	Parameters	Description
resetFilter	-	Resets filtering.


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

Name	Element
ui-dropdown	Container element.
ui-dropdown-label	Element to display label of selected option.
ui-dropdown-trigger	Icon element.
ui-dropdown-panel	Icon element.
ui-dropdown-items-wrapper	Wrapper element of items list.
ui-dropdown-items	List element of items.
ui-dropdown-item	An item in the list.
ui-dropdown-filter-container	Container of filter input.
ui-dropdown-filter	Filter element.
ui-dropdown-open	Container element when overlay is visible.

Dependencies

None.

View on GitHub


<h3 class="first">Single</h3>
<p-dropdown [options]="cities" [(ngModel)]="selectedCity" placeholder="Select a City" optionLabel="name"></p-dropdown>
<p>Selected City: {{selectedCity ? selectedCity.name : 'none'}}</p>

<h3>Editable</h3>
<p-dropdown [options]="cars" [(ngModel)]="selectedCar1" [style]="{'width':'150px'}" 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" [style]="{'width':'150px'}" 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">{{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" [style]="{'width':'150px'}" 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="vertical-align:middle">{{group.label}}</span>
    </ng-template>
</p-dropdown>


export class DropdownDemo {

    cities: City[];

    selectedCity: City;

    cars: SelectItem[];

    selectedCar1: string;

    selectedCar2: string = 'BMW';
    
    selectedCar3: string;

    groupedCars: SelectItemGroup[];

    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: 'Toyota', value: 'Toyota'}
                ]
            }
        ];
    }
}