Select

Select is used to choose an item from a collection of options.

Import #


import { SelectModule } from 'primeng/select';

Basic #

Select 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-select 
    [options]="cities" 
    [(ngModel)]="selectedCity" 
    optionLabel="name" 
    placeholder="Select a City" />

Reactive Forms #

Select 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-select 
        formControlName="selectedCity" 
        [options]="cities"
        optionLabel="name"
        placeholder="Select a City" />
</form>

Checkmark #

An alternative way to highlight the selected option is displaying a checkmark instead.


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

Editable #

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


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

Group #

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


<p-select 
    [options]="groupedCities" 
    [(ngModel)]="selectedCity" 
    placeholder="Select a City" 
    [group]="true">
    <ng-template let-group pTemplate="group">
        <div class="flex 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-select>

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 select 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-select 
    [options]="countries" 
    [(ngModel)]="selectedCountry"
    optionLabel="name"
    [showClear]="true"
    placeholder="Select a Country">
        <ng-template pTemplate="selectedItem">
            <div class="flex 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 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-select>

Filter #

Basic #

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


<p-select 
    [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 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 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-select>

Custom Filter #

Custom filter can be applied with the filterTemplate.


<p-select 
    [options]="countries" 
    [(ngModel)]="selectedCountry"
    optionLabel="name"
    [filter]="true" 
    filterBy="name"
    [showClear]="true"
    placeholder="Select a Country" 
    styleClass="w-80">
        <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 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 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-select>

Clear Icon #

When showClear is enabled, a clear icon is added to reset the Select.


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

Loading State #

Loading state can be used loading property.


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

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.


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

Lazy Virtual Scroll #


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

Float Label #

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

Select a City


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

Filled #

Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.


<p-select 
    [options]="cities" 
    [(ngModel)]="selectedCity"
    variant="filled"
    optionLabel="name" 
    placeholder="Select a City" />

Invalid #

Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.


<p-select
    [options]="cities"
    [(ngModel)]="selectedCity"
    optionLabel="name"
    [showClear]="true"
    placeholder="Select a City"
    class="ng-dirty ng-invalid"
/>

Disabled #

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


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

Accessibility #

Screen Reader

Value to describe the component can either be provided with ariaLabelledBy or ariaLabel props. The select 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-select ariaLabelledBy="dd1"/>

<p-select ariaLabel="Options"/>

Closed State Keyboard Support

Key	Function
tab	Moves focus to the select 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.

Popup Keyboard Support

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 select 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 select is editable, removes the visual focus from the current option and moves input cursor to one character left.
left arrow	If the select is editable, removes the visual focus from the current option and moves input cursor to one character right.
home	If the select is editable, moves input cursor at the end, if not then moves focus to the first option.
end	If the select 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 select is not editable.

Filter Input Keyboard Support

Key	Function
enter	Closes the popup and moves focus to the select element.
escape	Closes the popup and moves focus to the select element.

name	type	default	description
id	string	null	Unique identifier of the component
scrollHeight	string	200px	Height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value.
filter	boolean	false	When specified, displays an input field to filter the items on keyup.
name	string	null	Name of the input element.
style	Object	null	Inline style of the element.
panelStyle	Object	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.
readonly	boolean	false	When present, it specifies that the component cannot be edited.
required	boolean	false	When present, it specifies that an input field must be filled out before submitting the form.
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 (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having #mydiv as variable name).
tabindex	number	0	Index of the element in tabbing order.
placeholder	Signal<string>	null	Default text to display when no option is selected.
loadingIcon	string	null	Icon to display in loading state.
filterPlaceholder	string	null	Placeholder text to show when filter input is empty.
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
variant	"filled" \| "outlined"	outlined	Specifies the input variant of the component.
inputId	string	null	Identifier of the accessible input element.
dataKey	string	null	A property to uniquely identify a value in options.
filterBy	string	null	When filtering is enabled, filterBy decides which field or fields (comma separated) to search against.
filterFields	any[]	null	Fields used when filtering the options, defaults to optionLabel.
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 select.
checkmark	boolean	false	Whether the selected option will be shown with a check mark.
dropdownIcon	string	null	Icon class of the select icon.
loading	boolean	false	Whether the select is in loading state.
optionLabel	string	null	Name of the label field of an option.
optionValue	string	null	Name of the value field of an option.
optionDisabled	string	null	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.
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.
emptyFilterMessage	string	null	Text to display when filtering does not return any results. Defaults to global value in i18n translation configuration.
emptyMessage	string	null	Text to display when there is no data. Defaults to global value in i18n translation configuration.
lazy	boolean	false	Defines if data is loaded and interacted with in lazy manner.
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.
ariaFilterLabel	string	null	Defines a string that labels the filter input.
ariaLabel	string	null	Used to define a aria label attribute the current element.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
filterMatchMode	"endsWith" \| "startsWith" \| "contains" \| "equals" \| "in" \| "notEquals" \| "lt" \| "lte" \| "gt" \| "gte"	contains	Defines how the items are filtered.
maxlength	number	null	Maximum number of character allows in the editable input field.
tooltip	string	null	Advisory information to display in a tooltip on hover.
tooltipPosition	"left" \| "top" \| "bottom" \| "right"	right	Position of the tooltip.
tooltipPositionStyle	string	absolute	Type of CSS position.
tooltipStyleClass	string	null	Style class of the tooltip.
focusOnHover	boolean	true	Fields used when filtering the options, defaults to optionLabel.
selectOnFocus	boolean	false	Determines if the option will be selected on focus.
autoOptionFocus	boolean	true	Whether to focus on the first visible or selected element when the overlay panel is shown.
autofocusFilter	boolean	true	Applies focus to the filter element when the overlay is shown.
fluid	boolean	false	Whether the component should span the full width of its parent.
disabled	boolean	null	When present, it specifies that the component should be disabled.
itemSize	number	null	Item size of item to be virtual scrolled.
autoZIndex	boolean	null	Whether to automatically manage layering.
baseZIndex	number	null	Base zIndex value to use in layering.
showTransitionOptions	string	null	Transition options of the show animation.
hideTransitionOptions	string	null	Transition options of the hide animation.
filterValue	string	null	When specified, filter displays with this value.
options	any[]	null	An array of objects to display as the available options.

name	parameters	description
onChange	event : SelectChangeEvent	Callback to invoke when value of select changes.
onFilter	event : SelectFilterEvent	Callback to invoke when data is filtered.
onFocus	event : Event	Callback to invoke when select gets focus.
onBlur	event : Event	Callback to invoke when select loses focus.
onClick	event : MouseEvent	Callback to invoke when component is clicked.
onShow	event : AnimationEvent_2	Callback to invoke when select overlay gets visible.
onHide	event : AnimationEvent_2	Callback to invoke when select overlay gets hidden.
onClear	event : Event	Callback to invoke when select clears the value.
onLazyLoad	event : SelectLazyLoadEvent	Callback to invoke in lazy mode to load new data.

name	parameters	description
resetFilter		Callback to invoke on filter reset.
show	isFocus : any	Displays the panel.
hide	isFocus : any	Hides the panel.
focus		Applies focus.
clear	event : Event	Clears the model.

name	parameters	description
item	context : { $implicit: any, // Data of the option. }	Custom item template.
selectedItem	context : { $implicit: any, // Selected option value. }	Custom selected item template.
header		Custom header template.
filter	context : { options: SelectFilterOptions, // Filter options. }	Custom filter template.
footer		Custom footer template.
emptyfilter		Custom empty filter template.
empty		Custom empty template.
group	context : { $implicit: any, // Group option. }	Custom group template.
loader	context : { options: ScrollerOptions, // Virtual scroller options. }	Custom loader template. This template can be used with virtualScroll.
dropdownicon		Custom select icon template.
clearicon		Custom clear icon template.
filtericon		Custom filter icon template.

name	type	description
originalEvent	Event	Browser event.
value	any	Selected option value

Select

Import #

Basic #

Reactive Forms #

Checkmark #

Editable #

Group #

Template #

Filter #

Basic #

Custom Filter #

Clear Icon #

Loading State #

Virtual Scroll #

Lazy Virtual Scroll #

Float Label #

Filled #

Invalid #

Disabled #

Accessibility #

Screen Reader

Closed State Keyboard Support

Popup Keyboard Support

Filter Input Keyboard Support

Select API

Select #

Properties #

Emitters #

Methods #

Templates #

Events #

SelectChangeEvent #

SelectFilterEvent #

SelectLazyLoadEvent #

Interfaces #

SelectFilterOptions #

Select Theming

CSS Classes #

Select Design Tokens #

name	type	description
first	number	Index of the first element in viewport.
last	number	Index of the last element in viewport.

class	description
p-select	Class name of the root element
p-select-label	Class name of the label element
p-select-clear-icon	Class name of the clear icon element
p-select-dropdown	Class name of the dropdown element
p-select-loading-icon	Class name of the loadingicon element
p-select-dropdown-icon	Class name of the dropdown icon element
p-select-overlay	Class name of the overlay element
p-select-header	Class name of the header element
p-select-filter	Class name of the filter element
p-select-list-container	Class name of the list container element
p-select-list	Class name of the list element
p-select-option-group	Class name of the option group element
p-select-option-group-label	Class name of the option group label element
p-select-option	Class name of the option element
p-select-option-label	Class name of the option label element
p-select-option-check-icon	Class name of the option check icon element
p-select-option-blank-icon	Class name of the option blank icon element
p-select-empty-message	Class name of the empty message element

token	variable	description
root.background	--p-select-background	Background of root
root.disabledBackground	--p-select-disabled-background	Disabled background of root
root.filledBackground	--p-select-filled-background	Filled background of root
root.filledFocusBackground	--p-select-filled-focus-background	Filled focus background of root
root.borderColor	--p-select-border-color	Border color of root
root.hoverBorderColor	--p-select-hover-border-color	Hover border color of root
root.focusBorderColor	--p-select-focus-border-color	Focus border color of root
root.invalidBorderColor	--p-select-invalid-border-color	Invalid border color of root
root.color	--p-select-color	Color of root
root.disabledColor	--p-select-disabled-color	Disabled color of root
root.placeholderColor	--p-select-placeholder-color	Placeholder color of root
root.shadow	--p-select-shadow	Shadow of root
root.paddingX	--p-select-padding-x	Padding x of root
root.paddingY	--p-select-padding-y	Padding y of root
root.borderRadius	--p-select-border-radius	Border radius of root
focusRing.width	--p-select-focus-ring-width	Focus ring width of root
focusRing.style	--p-select-focus-ring-style	Focus ring style of root
focusRing.color	--p-select-focus-ring-color	Focus ring color of root
focusRing.offset	--p-select-focus-ring-offset	Focus ring offset of root
focusRing.shadow	--p-select-focus-ring-shadow	Focus ring shadow of root
root.transitionDuration	--p-select-transition-duration	Transition duration of root
dropdown.width	--p-select-dropdown-width	Width of dropdown
dropdown.color	--p-select-dropdown-color	Color of dropdown
overlay.background	--p-select-overlay-background	Background of overlay
overlay.borderColor	--p-select-overlay-border-color	Border color of overlay
overlay.borderRadius	--p-select-overlay-border-radius	Border radius of overlay
overlay.color	--p-select-overlay-color	Color of overlay
overlay.shadow	--p-select-overlay-shadow	Shadow of overlay
list.padding	--p-select-list-padding	Padding of list
list.gap	--p-select-list-gap	Gap of list
header.padding	--p-select-list-header-padding	Header padding of list
option.focusBackground	--p-select-option-focus-background	Focus background of option
option.selectedBackground	--p-select-option-selected-background	Selected background of option
option.selectedFocusBackground	--p-select-option-selected-focus-background	Selected focus background of option
option.color	--p-select-option-color	Color of option
option.focusColor	--p-select-option-focus-color	Focus color of option
option.selectedColor	--p-select-option-selected-color	Selected color of option
option.selectedFocusColor	--p-select-option-selected-focus-color	Selected focus color of option
option.padding	--p-select-option-padding	Padding of option
option.borderRadius	--p-select-option-border-radius	Border radius of option
optionGroup.background	--p-select-option-group-background	Background of option group
optionGroup.color	--p-select-option-group-color	Color of option group
optionGroup.fontWeight	--p-select-option-group-font-weight	Font weight of option group
optionGroup.padding	--p-select-option-group-padding	Padding of option group
clearIcon.color	--p-select-clear-icon-color	Color of clear icon
checkmark.color	--p-select-checkmark-color	Color of checkmark
checkmark.gutterStart	--p-select-checkmark-gutter-start	Gutter start of checkmark
checkmark.gutterEnd	--p-select-checkmark-gutter-end	Gutter end of checkmark
emptyMessage.padding	--p-select-empty-message-padding	Padding of empty message