Listbox

Listbox is used to select one or more values from a list of items.

Import #


import { ListboxModule } from 'primeng/listbox';

Basic #

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

No selected item


<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name" class="w-full md:w-56" />

Reactive Forms #

Listbox 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" class="card flex justify-center">
    <p-listbox [options]="cities" formControlName="selectedCity" optionLabel="name" class="w-full md:w-56" />
</form>

Checkmark #

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

No selected item


<p-listbox [(ngModel)]="selectedCity" [options]="cities" optionLabel="name" [checkmark]="true" [highlightOnSelect]="false" class="w-full md:w-56"/>

Checkbox #

Listbox allows item selection using checkboxes.


<p-listbox [(ngModel)]="selectedCity" [options]="cities" [multiple]="true" [checkbox]="true" optionLabel="name" class="w-full md:w-56" />

Multiple #

ListBox allows choosing a single item by default, enable multiple property to choose more than one. When the optional metaKeySelection is present, behavior is changed in a way that selecting a new item requires meta key to be present.

No selected item


<p-listbox [options]="cities" [(ngModel)]="selectedCities" optionLabel="name" [multiple]="true" [metaKeySelection]="false" class="w-full md:w-56" />

Group #

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


<p-listbox [options]="groupedCities" [group]="true" [(ngModel)]="selectedCountry" class="w-full md:w-56">
    <ng-template let-group #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-listbox>

Filter #

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

Search results are available

No selected item


<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name" [filter]="true" class="w-full md:w-56" />

Template #

For custom content support define a template named item where the default local template variable refers to an option.

No selected item


<p-listbox [options]="countries" [(ngModel)]="selectedCountry" optionLabel="name" class="w-full md:w-56">
    <ng-template #item let-country>
        <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-listbox>

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.

No selected item


<p-listbox [options]="items" [(ngModel)]="selectedItems" [selectAll]="selectAll" optionLabel="label" [virtualScroll]="true" [virtualScrollItemSize]="40" [multiple]="true" [metaKeySelection]="false" (onSelectAllChange)="onSelectAllChange($event)" (onChange)="onChange($event)" scrollHeight="250px" [striped]="true" class="w-full md:w-56" />

Invalid #

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

No selected item


<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name" class="ng-invalid ng-dirty w-full md:w-56" />

Disabled #

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

No selected item


<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name" [disabled]="true" class="w-full md:w-56" />

Accessibility #

Screen Reader

Value to describe the component can be provided ariaLabelledBy or ariaLabel props. The list element has a listbox role with the aria-multiselectable attribute that sets to true when multiple selection is enabled. Each list item has an option role with aria-selected and aria-disabled as their attributes.


<span id="lb">Options</span>
<p-listbox ariaLabelledBy="lb"/>

<p-listbox ariaLabel="City"/>

Keyboard Support

Key	Function
tab	Moves focus to the first selected option, if there is none then first option receives the focus.
up arrow	Moves focus to the previous option.
down arrow	Moves focus to the next option.
enter	Toggles the selected state of the focused option.
space	Toggles the selected state of the focused option.
home	Moves focus to the first option.
end	Moves focus to the last option.
shift + down arrow	Moves focus to the next option and toggles the selection state.
shift + up arrow	Moves focus to the previous option and toggles the selection state.
shift + space	Selects the items between the most recently selected option and the focused option.
control + shift + home	Selects the focused options and all the options up to the first one.
control + shift + end	Selects the focused options and all the options down to the last one.
control + a	Selects all options.

name	type	default	description
id	string	null	Unique identifier of the component.
searchMessage	string	'{0} results are available'	Text to display when the search is active. Defaults to global value in i18n translation configuration.
emptySelectionMessage	string	'No selected item'	Text to display when filtering does not return any results. Defaults to global value in i18n translation configuration.
selectionMessage	string	'{0} items selected'	Text to be displayed in hidden accessible field when options are selected. Defaults to global value in i18n translation configuration.
autoOptionFocus	boolean	true	Whether to focus on the first visible or selected element when the overlay panel is shown.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
selectOnFocus	boolean	false	When enabled, the focused option is selected.
searchLocale	boolean	false	Locale to use in searching. The default locale is the host environment's current locale.
focusOnHover	boolean	true	When enabled, the hovered option will be focused.
filterMessage	string	null	Text to display when filtering.
filterFields	any[]	null	Fields used when filtering the options, defaults to optionLabel.
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.
scrollHeight	string	14rem	Height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value.
tabindex	number	0	Index of the element in tabbing order.
multiple	boolean	false	When specified, allows selecting multiple values.
style	Object	null	Inline style of the container.
styleClass	string	null	Style class of the container.
listStyle	Object	null	Inline style of the list element.
listStyleClass	string	null	Style class of the list element.
readonly	boolean	false	When present, it specifies that the element value cannot be changed.
disabled	boolean	false	When present, it specifies that the element should be disabled.
checkbox	boolean	false	When specified, allows selecting items with checkboxes.
filter	boolean	false	When specified, displays a filter input at header.
filterBy	string	null	When filtering is enabled, filterBy decides which field or fields (comma separated) to search against.
filterMatchMode	"gt" \| "lt" \| "in" \| "startsWith" \| "contains" \| "endsWith" \| "equals" \| "notEquals" \| "lte" \| "gte"	contains	Defines how the items are filtered.
filterLocale	string	null	Locale to use in filtering. The default locale is the host environment's current locale.
metaKeySelection	boolean	false	Defines how multiple items can be selected, when true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically.
dataKey	string	null	A property to uniquely identify a value in options.
showToggleAll	boolean	true	Whether header checkbox is shown in multiple mode.
optionLabel	string	null	Name of the label field of an option.
optionValue	string	null	Name of the value field of an option.
optionGroupChildren	string	items	Name of the options field of an option group.
optionGroupLabel	string	label	Name of the label field of an option group.
optionDisabled	string	null	Name of the disabled field of an option.
ariaFilterLabel	string	null	Defines a string that labels the filter input.
filterPlaceHolder	string	null	Defines placeholder of the filter input.
emptyFilterMessage	string	null	Text to display when filtering does not return any results.
emptyMessage	string	null	Text to display when there is no data. Defaults to global value in i18n translation configuration.
group	boolean	false	Whether to display options as grouped when nested options are provided.
options	any[]	null	An array of selectitems to display as the available options.
filterValue	string	null	When specified, filter displays with this value.
selectAll	boolean	null	Whether all data is selected.
striped	boolean	false	Whether to displays rows with alternating colors.
highlightOnSelect	boolean	true	Whether the selected option will be add highlight class.
checkmark	boolean	false	Whether the selected option will be shown with a check mark.

name	parameters	description
onChange	event : ListboxChangeEvent	Callback to invoke on value change.
onClick	event : ListboxClickEvent	Callback to invoke when option is clicked.
onDblClick	event : ListboxDoubleClickEvent	Callback to invoke when option is double clicked.
onFilter	event : ListboxFilterEvent	Callback to invoke when data is filtered.
onFocus	event : FocusEvent	Callback to invoke when component receives focus.
onBlur	event : FocusEvent	Callback to invoke when component loses focus.
onSelectAllChange	event : ListboxSelectAllChangeEvent	Callback to invoke when all data is selected.
onLazyLoad	event : ScrollerLazyLoadEvent	Emits on lazy load.

name	parameters	description
item	context : { $implicit: any, // Data of the option. index: number, // Index of the option. }	Custom item template.
group	context : { $implicit: any, // Group option. }	Custom group template.
header		Custom header template.
filter	context : { options: ListboxFilterOptions, // Filter options. }	Custom filter template.
footer		Custom footer template.
empty		Custom empty template.
emptyfilter		Custom empty filter template.
filtericon		Custom filter icon template.
checkicon		Custom check icon template.
checkmark	context : { $implicit: boolean, // Selection status. }	Custom checkmark template.

name	type	description
originalEvent	Event	Original event
value	any	Selected option value

name	type	description
originalEvent	Event	Browser event.
checked	boolean	Boolean value indicates whether all data is selected.

Listbox

Import #

Basic #

Reactive Forms #

Checkmark #

Checkbox #

Multiple #

Group #

Filter #

Template #

Virtual Scroll #

Invalid #

Disabled #

Accessibility #

Screen Reader

Keyboard Support

Listbox API

Listbox #

Properties #

Emitters #

Methods #

Templates #

Events #

ListboxChangeEvent #

ListboxSelectAllChangeEvent #

ListboxFilterEvent #

ListboxClickEvent #

ListboxDoubleClickEvent #

Interfaces #

ListboxFilterOptions #

Listbox Theming

CSS Classes #

Listbox Design Tokens #

Built-in Presets #

name	type	description
filter	Function	Callback to filter options.
reset	Function	Callback to reset filter.

class	description
p-listbox	Class name of the root element
p-listbox-header	Class name of the header element
p-listbox-filter	Class name of the filter element
p-listbox-list-container	Class name of the list container element
p-listbox-list	Class name of the list element
p-listbox-option-group	Class name of the option group element
p-listbox-option	Class name of the option element
p-listbox-option-check-icon	Class name of the option check icon element
p-listbox-option-blank-icon	Class name of the option blank icon element
p-listbox-empty-message	Class name of the empty message element

token	variable	description
listbox.background	--p-listbox-background	Background of root
listbox.disabled.background	--p-listbox-disabled-background	Disabled background of root
listbox.border.color	--p-listbox-border-color	Border color of root
listbox.hover.border.color	--p-listbox-hover-border-color	Hover border color of root
listbox.focus.border.color	--p-listbox-focus-border-color	Focus border color of root
listbox.invalid.border.color	--p-listbox-invalid-border-color	Invalid border color of root
listbox.color	--p-listbox-color	Color of root
listbox.disabled.color	--p-listbox-disabled-color	Disabled color of root
listbox.shadow	--p-listbox-shadow	Shadow of root
listbox.border.radius	--p-listbox-border-radius	Border radius of root
listbox.focus.ring.width	--p-listbox-focus-ring-width	Focus ring width of root
listbox.focus.ring.style	--p-listbox-focus-ring-style	Focus ring style of root
listbox.focus.ring.color	--p-listbox-focus-ring-color	Focus ring color of root
listbox.focus.ring.offset	--p-listbox-focus-ring-offset	Focus ring offset of root
listbox.focus.ring.shadow	--p-listbox-focus-ring-shadow	Focus ring shadow of root
listbox.transition.duration	--p-listbox-transition-duration	Transition duration of root
listbox.list.padding	--p-listbox-list-padding	Padding of list
listbox.list.gap	--p-listbox-list-gap	Gap of list
listbox.list.header.padding	--p-listbox-list-header-padding	Header padding of list
listbox.option.focus.background	--p-listbox-option-focus-background	Focus background of option
listbox.option.selected.background	--p-listbox-option-selected-background	Selected background of option
listbox.option.selected.focus.background	--p-listbox-option-selected-focus-background	Selected focus background of option
listbox.option.color	--p-listbox-option-color	Color of option
listbox.option.focus.color	--p-listbox-option-focus-color	Focus color of option
listbox.option.selected.color	--p-listbox-option-selected-color	Selected color of option
listbox.option.selected.focus.color	--p-listbox-option-selected-focus-color	Selected focus color of option
listbox.option.padding	--p-listbox-option-padding	Padding of option
listbox.option.border.radius	--p-listbox-option-border-radius	Border radius of option
listbox.option.striped.background	--p-listbox-option-striped-background	Striped background of option
listbox.option.group.background	--p-listbox-option-group-background	Background of option group
listbox.option.group.color	--p-listbox-option-group-color	Color of option group
listbox.option.group.font.weight	--p-listbox-option-group-font-weight	Font weight of option group
listbox.option.group.padding	--p-listbox-option-group-padding	Padding of option group
listbox.checkmark.color	--p-listbox-checkmark-color	Color of checkmark
listbox.checkmark.gutter.start	--p-listbox-checkmark-gutter-start	Gutter start of checkmark
listbox.checkmark.gutter.end	--p-listbox-checkmark-gutter-end	Gutter end of checkmark
listbox.empty.message.padding	--p-listbox-empty-message-padding	Padding of empty message

Preset	Implementation	Types
Aura	Aura	Aura
Lara	Lara	Lara
Nora	Nora	Nora
Material	Material	Material