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.


<p-listbox 
    [options]="cities" 
    [(ngModel)]="selectedCity" 
    optionLabel="name" 
    [style]="{'width':'15rem'}" 
    [listStyle]="{'max-height': '220px'}" />

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">
    <p-listbox 
        [options]="cities" 
        formControlName="selectedCity" 
        optionLabel="name" 
        [style]="{ width: '15rem' }" 
        [listStyle]="{'max-height': '220px'}" />
</form>

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.


<p-listbox 
    [options]="cities" 
    [(ngModel)]="selectedCities" 
    optionLabel="name" 
    [style]="{'width':'15rem'}" 
    [multiple]="true" 
    [metaKeySelection]="false" 
    [listStyle]="{'max-height': '220px'}" />

Group #

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


<p-listbox 
    [options]="groupedCities" 
    [group]="true" 
    [(ngModel)]="selectedCountry" 
    [listStyle]="{ 'max-height': '250px' }" 
    [style]="{ width: '15rem' }">
        <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-listbox>

Filter #

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

5 results are available


<p-listbox 
    [options]="cities" 
    [(ngModel)]="selectedCity"
    optionLabel="name" 
    [filter]="true" 
    [style]="{ width: '15rem' }" 
    [listStyle]="{'max-height': '220px'}" />

Template #

Custom content for an option is displayed with the pTemplate property that takes an option as a parameter.


<p-listbox 
    [options]="countries" 
    [(ngModel)]="selectedCountry" 
    optionLabel="name" 
    [listStyle]="{ 'max-height': '250px' }" 
    [style]="{ width: '15rem' }" 
    [listStyle]="{'max-height': '220px'}">
        <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-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.


<p-listbox
    [options]="items"
    [(ngModel)]="selectedItems"
    [selectAll]="selectAll"
    optionLabel="label"
    [style]="{ width: '15rem' }"
    [virtualScroll]="true"
    [virtualScrollItemSize]="38"
    [multiple]="true"
    [metaKeySelection]="false"
    (onSelectAllChange)="onSelectAllChange($event)"
    (onChange)="onChange($event)"
    scrollHeight="250px" />

Invalid #

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


<p-listbox 
    [options]="cities" 
    [(ngModel)]="selectedCity" 
    optionLabel="name" 
    class="ng-invalid ng-dirty" 
    [style]="{ width: '15rem' }" 
    [listStyle]="{'max-height': '220px'}" />

Disabled #

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


<p-listbox 
    [options]="cities" 
    [(ngModel)]="selectedCity" 
    optionLabel="name" 
    [disabled]="true" 
    [style]="{ width: '15rem' }" 
    [listStyle]="{'max-height': '220px'}" />

Style #

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

Name	Element
p-listbox	Container element.
p-listbox-list	List container.
p-listbox-item	An item in the list.
p-listbox-header	Header element.
p-listbox-filter-container	Container of filter input in header.

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.

Listbox API

API defines helper props, events and others for the PrimeNG Listbox module.

Listbox #

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

Properties #

Defines the input properties of the component.

name	type	default	description
id	string	null	Unique identifier of the component.
searchMessage	string	null	Text to display when the search is active. Defaults to global value in i18n translation configuration.
emptySelectionMessage	string	null	Text to display when filtering does not return any results. Defaults to global value in i18n translation configuration.
selectionMessage	string	null	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	false	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	200px	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	"endsWith" \| "startsWith" \| "contains" \| "equals" \| "notEquals" \| "in" \| "lt" \| "lte" \| "gt" \| "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.

Emitters #

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

Methods #

Defines methods that can be accessed by the component's reference.

name	parameters	description
updateModel	value : any event : any	Updates the model value.

Templates #

Defines the templates used by the component.

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.

Events #

Defines the custom events used by the component's emitters.

ListboxChangeEvent #

Custom change event.

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

ListboxSelectAllChangeEvent #

Custom change event.

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

ListboxFilterEvent #

Custom filter event.

name	type	description
originalEvent	Event	Browser event.
filter	any	Filter value.

ListboxClickEvent #

Custom change event.

name	type	description
originalEvent	Event	Browser event.
value	any	Value of the component.
option	any	Selected option

ListboxDoubleClickEvent #

Custom change event.

name	type	description
originalEvent	Event	Browser event.
value	any	Value of the component.
option	any	Selected option

Interfaces #

Defines the custom interfaces used by the module.

ListboxFilterOptions #

Filter options of listbox.

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