Dropdown also known as Select, is used to choose an item from a collection of options.
import { DropdownModule } from 'primeng/dropdown';
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. Note that, when options are simple primitive values such as a string array, no optionLabel and optionValue would be necessary.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
optionLabel="name"
placeholder="Select a City" />
Dropdown can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.
<form [formGroup]="formGroup">
<p-dropdown
formControlName="selectedCity"
[options]="cities"
optionLabel="name"
placeholder="Select a City" />
</form>
An alternative way to highlight the selected option is displaying a checkmark instead.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
[checkmark]="true"
optionLabel="name"
[showClear]="true"
placeholder="Select a City" />
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" />
Options can be grouped when a nested data structures is provided.
<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>
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.
<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>
Dropdown provides built-in filtering that is enabled by adding the filter property.
<p-dropdown
[options]="countries"
[(ngModel)]="selectedCountry"
optionLabel="name"
[filter]="true"
filterBy="name"
[showClear]="true"
placeholder="Select a Country">
<ng-template pTemplate="selectedItem" let-selectedOption>
<div class="flex align-items-center gap-2">
<img
src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png"
[class]="'flag flag-' + selectedCountry.code.toLowerCase()"
style="width: 18px" />
<div>{{ selectedOption.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>
Custom filter can be applied with the filterTemplate.
<p-dropdown
[options]="countries"
[(ngModel)]="selectedCountry"
optionLabel="name"
[filter]="true"
filterBy="name"
[showClear]="true"
placeholder="Select a Country"
styleClass="w-20rem">
<ng-template pTemplate="filter" let-options="options">
<div class="flex gap-1">
<div class="p-inputgroup" (click)="$event.stopPropagation()">
<span class="p-inputgroup-addon"><i class="pi pi-search"></i></span>
<input
type="text"
pInputText
placeholder="Filter"
[(ngModel)]="filterValue"
(keyup)="customFilterFunction($event, options)" />
</div>
<button pButton icon="pi pi-times" (click)="resetFunction(options)" severity="secondary"></button>
</div>
</ng-template>
<ng-template pTemplate="selectedItem" let-selectedOption>
<div class="flex align-items-center gap-2">
<img
src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png"
[class]="'flag flag-' + selectedCountry.code.toLowerCase()"
style="width: 18px" />
<div>{{ selectedOption.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>
When showClear is enabled, a clear icon is added to reset the Dropdown.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
optionLabel="name"
[showClear]="true"
placeholder="Select a City" />
Loading state can be used loading property.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
[loading]="true"
optionLabel="name"
placeholder="Select a City" />
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.
<p-dropdown
[options]="items"
[(ngModel)]="selectedItem"
placeholder="Select Item"
[virtualScroll]="true"
[virtualScrollItemSize]="38" />
<p-dropdown
[options]="items"
[(ngModel)]="selectedItem"
placeholder="Select Item"
[virtualScroll]="true"
[virtualScrollItemSize]="38"
[virtualScrollOptions]="options" />
A floating label appears on top of the input field when focused.
<p-floatLabel>
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
optionLabel="name"
inputId="float-label" />
<label for="float-label">Select a City</label>
</p-floatLabel>
Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
variant="filled"
optionLabel="name"
placeholder="Select a City" />
Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
optionLabel="name"
[showClear]="true"
placeholder="Select a City"
class="ng-dirty ng-invalid" />
When disabled is present, the element cannot be edited and focused.
<p-dropdown
[options]="cities"
[(ngModel)]="selectedCity"
placeholder="Select a City"
optionLabel="name"
[disabled]="true" />
Following is the list of structural style classes, for theming classes visit theming page.
Name | Element |
---|---|
p-dropdown | Container element. |
p-dropdown-clearable | Container element when showClear is on. |
p-dropdown-label | Element to display label of selected option. |
p-dropdown-trigger | Icon element. |
p-dropdown-panel | Icon element. |
p-dropdown-items-wrapper | Wrapper element of items list. |
p-dropdown-items | List element of items. |
p-dropdown-item | An item in the list. |
p-dropdown-filter-container | Container of filter input. |
p-dropdown-filter | Filter element. |
p-dropdown-open | Container element when overlay is visible. |
Value to describe the component can either be provided with ariaLabelledBy or ariaLabel 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 ariaLabelledBy="dd1"/>
<p-dropdown ariaLabel="Options"/>
Key | Function |
---|---|
tab | Moves focus to the dropdown element. |
space | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
down arrow | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
up arrow | Opens the popup and moves visual focus to the selected option, if there is none then last option receives the focus. |
Key | Function |
---|---|
tab | Moves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus. |
shift + tab | Moves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus. |
enter | Selects the focused option and closes the popup. |
space | Selects the focused option and closes the popup. |
escape | Closes the popup, moves focus to the dropdown element. |
down arrow | Moves focus to the next option, if there is none then visual focus does not change. |
up arrow | Moves focus to the previous option, if there is none then visual focus does not change. |
right arrow | If the dropdown is editable, removes the visual focus from the current option and moves input cursor to one character left. |
left arrow | If the dropdown is editable, removes the visual focus from the current option and moves input cursor to one character right. |
home | If the dropdown is editable, moves input cursor at the end, if not then moves focus to the first option. |
end | If the dropdown is editable, moves input cursor at the beginning, if not then moves focus to the last option. |
any printable character | Moves focus to the option whose label starts with the characters being typed if dropdown is not editable. |
Key | Function |
---|---|
enter | Closes the popup and moves focus to the dropdown element. |
escape | Closes the popup and moves focus to the dropdown element. |
API defines helper props, events and others for the PrimeNG Dropdown module.
Dropdown also known as Select, is used to choose an item from a collection of options.
Defines the input properties of the component.
Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.
name | parameters | description | |
---|---|---|---|
onChange | event : DropdownChangeEvent | Callback to invoke when value of dropdown changes. | |
onFilter | event : DropdownFilterEvent | Callback to invoke when data is filtered. | |
onFocus | event : Event | Callback to invoke when dropdown gets focus. | |
onBlur | event : Event | Callback to invoke when dropdown loses focus. | |
onClick | event : MouseEvent | Callback to invoke when component is clicked. | |
onShow | event : AnimationEvent_2 | Callback to invoke when dropdown overlay gets visible. | |
onHide | event : AnimationEvent_2 | Callback to invoke when dropdown overlay gets hidden. | |
onClear | event : Event | Callback to invoke when dropdown clears the value. | |
onLazyLoad | event : DropdownLazyLoadEvent | Callback to invoke in lazy mode to load new data. |
Defines methods that can be accessed by the component's reference.
Defines the templates used by the component.
Defines the custom events used by the component's emitters.
Custom change event.
Custom filter event.
Custom lazy load event.
Defines the custom interfaces used by the module.
Filter callbacks of the dropdown.