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.

  • New York
  • Rome
  • London
  • Istanbul
  • Paris


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

  • New York
  • Rome
  • London
  • Istanbul
  • Paris


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

  • New York
  • Rome
  • London
  • Istanbul
  • Paris


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

  • Australia
  • Brazil
  • China
  • Egypt
  • France
  • Germany
  • India
  • Japan
  • Spain
  • United States


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

  • Germany
  • Berlin
  • Frankfurt
  • Hamburg
  • Munich
  • USA
  • Chicago
  • Los Angeles
  • New York
  • San Francisco
  • Japan
  • Kyoto
  • Osaka
  • Tokyo
  • Yokohama


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

  • New York
  • Rome
  • London
  • Istanbul
  • Paris


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

  • New York
  • Rome
  • London
  • Istanbul
  • Paris


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

  • New York
  • Rome
  • London
  • Istanbul
  • Paris


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

NameElement
p-listboxContainer element.
p-listbox-listList container.
p-listbox-itemAn item in the list.
p-listbox-headerHeader element.
p-listbox-filter-containerContainer 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

KeyFunction
tabMoves focus to the first selected option, if there is none then first option receives the focus.
up arrowMoves focus to the previous option.
down arrowMoves focus to the next option.
enterToggles the selected state of the focused option.
spaceToggles the selected state of the focused option.
homeMoves focus to the first option.
endMoves focus to the last option.
shift + down arrowMoves focus to the next option and toggles the selection state.
shift + up arrowMoves focus to the previous option and toggles the selection state.
shift + spaceSelects the items between the most recently selected option and the focused option.
control + shift + homeSelects the focused options and all the options up to the first one.
control + shift + endSelects the focused options and all the options down to the last one.
control + aSelects all options.
PrimeNG 16.0.0-rc.2 by PrimeTek