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'}"></p-listbox>

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' }"></p-listbox>
</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"></p-listbox>

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' }">
    <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>

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.



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

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' }"></p-listbox>

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' }"></p-listbox>

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 guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility #

Screen Reader

Value to describe the component can be provided aria-labelledby or aria-label 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.

If filtering is enabled, filterInputProps can be defined to give aria-* props to the input element. Alternatively filterPlaceholder is usually utilized by the screen readers as well.


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

<p-listbox aria-label="City"></p-listbox>

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
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	true	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	null	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.

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.

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

ListboxClickEvent #

Custom change event.

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

ListboxDoubleClickEvent #

Custom change event.

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

Interfaces #

Defines the custom interfaces used by the module.

ListboxFilterOptions #

Filter options of listbox.

name	type	description
filter	Function
reset	Function