Dropdown

Dropdown also known as Select, is used to choose an item from a collection of options.

Import #


import { DropdownModule } from 'primeng/dropdown';

Basic #

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

New York


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

Reactive Forms #

Dropdown can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.

New York


<form [formGroup]="formGroup">
    <p-dropdown formControlName="city" [options]="cities" optionLabel="name"></p-dropdown>
</form>

Editable #

When editable is present, the input can also be entered with typing.



<p-dropdown [options]="cities" [(ngModel)]="selectedCity" placeholder="Select a City" [editable]="true" optionLabel="name"></p-dropdown>

Group #

Options can be grouped when a nested data structures is provided.

Select a City


<p-dropdown [options]="groupedCities" [(ngModel)]="selectedCity" placeholder="Select a City" [group]="true">
    <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-dropdown>

Template #

Both the selected option and the options list can be templated to provide customizated representation. 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.

Select a Country


<p-dropdown [options]="countries" [(ngModel)]="selectedCountry" optionLabel="name" [showClear]="true" placeholder="Select a Country">
    <ng-template pTemplate="selectedItem">
        <div class="flex align-items-center gap-2" *ngIf="selectedCountry">
            <img src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + selectedCountry.code.toLowerCase()" style="width: 18px"/>
            <div>{{ selectedCountry.name }}</div>
        </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-dropdown>

Filter #

Dropdown provides built-in filtering that is enabled by adding the filter property.

Select a Country


<p-dropdown [options]="countries" [(ngModel)]="selectedCountry" optionLabel="name" [filter]="true" filterBy="name" [showClear]="true" placeholder="Select a Country">
    <ng-template pTemplate="selectedItem">
        <div class="flex align-items-center gap-2" *ngIf="selectedCountry">
            <img src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + selectedCountry.code.toLowerCase()" style="width: 18px"/>
            <div>{{ selectedCountry.name }}</div>
        </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-dropdown>

Virtual Scroll #

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.

Select Item


<p-dropdown [options]="items" [(ngModel)]="selectedItem" placeholder="Select Item" 
    [virtualScroll]="true" [virtualScrollItemSize]="38"></p-dropdown>

Disabled #

When disabled is present, the element cannot be edited and focused.

Select a City


<p-dropdown [options]="cities" [(ngModel)]="selectedCity" placeholder="Select a City" optionLabel="name" [disabled]="true"></p-dropdown>

Float Label #

A floating label appears on top of the input field when focused.

Select a City


<span class="p-float-label">
    <p-dropdown [options]="cities" [(ngModel)]="selectedCity" placeholder="Select a City" optionLabel="name" inputId="float-label"></p-dropdown>
    <label for="float-label">Select a City</label>
</span>

Style #

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

NameElement
p-dropdownContainer element.
p-dropdown-clearableContainer element when showClear is on.
p-dropdown-labelElement to display label of selected option.
p-dropdown-triggerIcon element.
p-dropdown-panelIcon element.
p-dropdown-items-wrapperWrapper element of items list.
p-dropdown-itemsList element of items.
p-dropdown-itemAn item in the list.
p-dropdown-filter-containerContainer of filter input.
p-dropdown-filterFilter element.
p-dropdown-openContainer element when overlay is visible.
Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility #

Screen Reader

Value to describe the component can either be provided with aria-labelledby or aria-label props. The dropdown element has a combobox role in addition to aria-haspopup and aria-expanded attributes. If the editable option is enabled aria-autocomplete is also added. The relation between the combobox and the popup is created with aria-controls and aria-activedescendant attribute is used to instruct screen reader which option to read during keyboard navigation within the popup list.

The popup list has an id that refers to the aria-controls attribute of the combobox element and uses listbox as the role. Each list item has an option role, an id to match the aria-activedescendant of the input element along with aria-label, aria-selected and aria-disabled attributes.

If filtering is enabled, filterInputProps can be defined to give aria-* props to the filter input element.


<span id="dd1">Options</span>
<p-dropdown aria-labelledby="dd1"></p-dropdown>

<p-dropdown aria-label="Options"></p-dropdown>

Closed State Keyboard Support

KeyFunction
tabMoves focus to the dropdown element.
spaceOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.
down arrowOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.
up arrowOpens the popup and moves visual focus to the selected option, if there is none then last option receives the focus.

Popup Keyboard Support

KeyFunction
tabMoves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus.
shift + tabMoves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus.
enterSelects the focused option and closes the popup.
spaceSelects the focused option and closes the popup.
escapeCloses the popup, moves focus to the dropdown element.
down arrowMoves focus to the next option, if there is none then visual focus does not change.
up arrowMoves focus to the previous option, if there is none then visual focus does not change.
right arrowIf the dropdown is editable, removes the visual focus from the current option and moves input cursor to one character left.
left arrowIf the dropdown is editable, removes the visual focus from the current option and moves input cursor to one character right.
homeIf the dropdown is editable, moves input cursor at the end, if not then moves focus to the first option.
endIf the dropdown is editable, moves input cursor at the beginning, if not then moves focus to the last option.
any printable characterMoves focus to the option whose label starts with the characters being typed if dropdown is not editable.

Filter Input Keyboard Support

KeyFunction
enterCloses the popup and moves focus to the dropdown element.
escapeCloses the popup and moves focus to the dropdown element.
PrimeNG 16.0.0-rc.2 by PrimeTek