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. 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.
<p-dropdown [options]="cities" [(ngModel)]="selectedCity" optionLabel="name"></p-dropdown>
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="city" [options]="cities" optionLabel="name"></p-dropdown>
</form>
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>
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">
<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>
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>
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"></p-dropdown>
A floating label appears on top of the input field when focused.
<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>
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 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>
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.
Name | Type | Default | Description |
---|---|---|---|
options | array | null | An array of objects to display as the available options. |
optionLabel | string | label | Name of the label field of an option. |
optionValue | string | value | Name of the value field of an option. |
optionDisabled | string | disabled | Name of the disabled field of an option. |
optionGroupLabel | string | label | Name of the label field of an option group. |
optionGroupChildren | string | items | Name of the options field of an option group. |
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. |
filterValue | string | null | When specified, filter displays with this value. |
filterBy | string | null | When filtering is enabled, filterBy decides which field or fields (comma separated) to search against. |
filterMatchMode | string | contains | Defines how the items are filtered, valid values are "contains" (default) "startsWith", "endsWith", "equals", "notEquals", "in", "lt", "lte", "gt" and "gte". |
filterPlaceholder | string | null | Placeholder text to show when filter input is empty. |
filterLocale | string | undefined | Locale to use in filtering. The default locale is the host environment's current locale. |
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. |
readonly | boolean | false | When present, it specifies that the component cannot be edited. |
emptyMessage | string | No records found. | Text to display when there is no data. Defaults to global value in i18n translation configuration. |
emptyFilterMessage | string | No results found | Text to display when filtering does not return any results. Defaults to global value in i18n translation configuration. |
ariaLabelledBy | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
editable | boolean | false | When present, custom value instead of predefined options can be entered using the editable input field. |
maxlength | number | null | Maximum number of character allows in 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 (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having #mydiv as variable name). |
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 accessible input element. |
dataKey | string | null | A property to uniquely identify a value in options. |
autofocus | boolean | false | When present, it specifies that the component should automatically get focus on load. |
autofocusFilter | boolean | false | Applies focus to the filter element when the overlay is shown. |
resetFilterOnHide | boolean | false | Clears the filter value when hiding the dropdown. |
dropdownIcon | string | null | Icon class of the dropdown icon. |
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. |
showClear | boolean | false | When enabled, a clear icon is displayed to clear the value. |
baseZIndex | number | 0 | Base zIndex value to use in layering. |
autoZIndex | boolean | true | Whether to automatically manage layering. |
showTransitionOptions | string | .12s cubic-bezier(0, 0, 0.2, 1) | Transition options of the show animation. |
hideTransitionOptions | string | .1s linear | Transition options of the hide animation. |
ariaFilterLabel | string | null | Defines a string that labels the filter input. |
ariaLabel | string | null | Used to define a string that autocomplete attribute the current element. |
tooltip | any | null | Advisory information to display in a tooltip on hover. |
tooltipStyleClass | string | null | Style class of the tooltip. |
tooltipPosition | string | top | Position of the tooltip, valid values are right, left, top and bottom. |
tooltipPositionStyle | string | absolute | Type of CSS position. |
virtualScroll | boolean | false | Whether the data should be loaded on demand during scroll. |
virtualScrollItemSize | number | null | Height of an item in the list for VirtualScrolling. |
virtualScrollOptions | ScrollerOptions | null | Whether to use the scroller feature. The properties of scroller component can be used like an object in it. |
overlayOptions | OverlayOptions | null | Whether to use overlay API feature. The properties of overlay API can be used like an object in it. |
lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
Name | Parameters | Description |
---|---|---|
onClick | event: Click event | Callback to invoke when component is clicked. |
onChange | event.originalEvent: Browser event event.value: Selected option value | Callback to invoke when value of dropdown changes. |
onFilter | event.originalEvent: Browser event event.filter: Filter value used in filtering. | Callback to invoke when data is filtered. |
onFocus | event: Browser event | Callback to invoke when dropdown gets focus. |
onBlur | event: Browser event | Callback to invoke when dropdown loses focus. |
onShow | event: Animation event | Callback to invoke when dropdown overlay gets visible. |
onHide | event: Animation event | Callback to invoke when dropdown overlay gets hidden. |
onClear | event: Animation event | Callback to invoke when dropdown clears the value. |
onLazyLoad | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke in lazy mode to load new data. |
Name | Parameters | Description |
---|---|---|
resetFilter | - | Resets filtering. |
focus | - | Applies focus. |
show | - | Displays the panel. |
hide | - | Hides the panel. |
Name | Parameters |
---|---|
item | $implicit: Data of the option |
group | $implicit: Group option |
selectedItem | $implicit: value |
header | - |
filter | options.filter: Callback to filter data by the value param options.reset: Resets the filter. |
empty | - |
emptyfilter | - |
footer | - |
loader | options: Options of the scroller on loading. *This template can be used with virtualScroll. |
dropdownicon | - |
clearicon | - |
filtericon | - |