Listbox is used to select one or more values from a list of items.
import { ListboxModule } from 'primeng/listbox';
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>
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>
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>
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>
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>
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 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>
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>
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. |
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>
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. |
API defines helper props, events and others for the PrimeNG Listbox module.
Name | Type | Default | Description |
---|---|---|---|
ariaFilterLabel | string | null | Defines a string that labels the filter input. |
checkbox | boolean | false | When specified, allows selecting items with checkboxes. |
dataKey | string | null | A property to uniquely identify a value in options. |
disabled | boolean | false | When present, it specifies that the element should be disabled. |
filter | boolean | false | When specified, displays a filter input at header. |
filterMatchMode | string | contains | Defines how the items are filtered, valid values are "contains" (default) "startsWith", "endsWith", "equals", "notEquals", "in", "lt", "lte", "gt" and "gte". |
filterValue | string | null | When specified, filter displays with this value. |
filterLocale | string | undefined | Locale to use in filtering. The default locale is the host environment's current locale. |
filterBy | string | null | When filtering is enabled, filterBy decides which field or fields (comma separated) to search against. |
filterPlaceHolder | string | null | Defines placeholder of the filter input. |
emptyFilterMessage | string | No results found | Text to display when filtering does not return any results. |
listStyle | string | null | Inline style of the list element. |
listStyleClass | string | null | Style class of the list element. |
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. |
multiple | boolean | false | When specified, allows selecting multiple values. |
readonly | boolean | false | When present, it specifies that the element value cannot be changed. |
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. |
options | array | null | An array of selectitems 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. |
group | boolean | false | Whether to display options as grouped when nested options are provided. |
showToggleAll | boolean | true | Whether header checkbox is shown in multiple mode. |
style | string | null | Inline style of the container. |
styleClass | string | null | Style class of the container. |
Name | Parameters | Description |
---|---|---|
onChange | event.originalEvent: browser event event.value: single value or an array of values that are selected | Callback to invoke when value of listbox changes. |
onDblClick | event.originalEvent: browser event event.value: single value or an array of values that are selected event.option: option that are clicked | Callback to invoke when an item is double clicked. |
onClick | event.originalEvent: browser event event.value: single value or an array of values that are selected event.option: option that are clicked | Callback to invoke when listbox option clicks. |
Name | Parameters |
---|---|
item | $implicit: Data of the option index: Index of the option |
group | $implicit: Group option |
header | - |
filter | options.filter: Callback to filter data by the value param options.reset: Resets the filter. |
empty | - |
emptyfilter | - |
footer | - |
filtericon | - |
checkicon | - |