Getting Started

Listbox requires a value to bind and a collection of options. There are two alternatives of how to define the options property; one way is providing a collection of SelectItem instances whereas other way is providing an array of arbitrary objects along with the optionLabel property to specify the field name of the option. SelectItem API is designed to have more control on how the options are displayed such as grouping and disabling however in most cases an arbitrary object collection will suffice. Example below demonstrates both cases.

<p-listbox [options]="cities1" [(ngModel)]="selectedCity1"></p-listbox>
<p-listbox [options]="cities2" [(ngModel)]="selectedCity2" optionLabel="name"></p-listbox>
 

import {SelectItem} from 'primeng/api';
export class MyModel {
    cities1: SelectItem[];
    cities2: City[];
    selectedCity1: City;
    selectedCity2: City;
    constructor() {
        //SelectItem API with label-value pairs
        this.cities1 = [
            {label:'Select City', value:null},
            {label:'New York', value:{id:1, name: 'New York', code: 'NY'}},
            {label:'Rome', value:{id:2, name: 'Rome', code: 'RM'}},
            {label:'London', value:{id:3, name: 'London', code: 'LDN'}},
            {label:'Istanbul', value:{id:4, name: 'Istanbul', code: 'IST'}},
            {label:'Paris', value:{id:5, name: 'Paris', code: 'PRS'}}
        ];
        //An array of cities
        this.cities2 = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
    }
}
 

Selection

Listbox allows selection of either single or multiple items whereas checkbox option displays a checkbox to indicate multiple selection. In single case, model should be a single object reference whereas in multiple case should be an array. Multiple items can either be selected using metaKey or toggled individually depending on the value of metaKeySelection property value which is true by default. On touch enabled devices metaKeySelection is turned off automatically.

<p-listbox [options]="cities" [(ngModel)]="selectedCities"></p-listbox>
 

Updating Options

addOption() {
    //fails
    this.options.push({name:'New York', code: 'NY'});
    //correct
}
 

Particular options can be prevented from selection using the disabled property of SelectItem API.

Filter

Filtering allows searching items in the list using an input field at the header. In order to use filtering, enable filter property. Default filtering mode is "contains" and alternative is "startsWith" configuted by filterMode property.

<p-listbox [options]="cities" [(ngModel)]="selectedCities" filter="filter"></p-listbox>
 

Model Driven Forms

Listbox can be used in a model driven form as well.

<p-listbox [options]="cities" formControlName="cities"></p-listbox>
 

Custom Content

import {SelectItem} from 'primeng/api';
export class MyModel {
    cars: SelectItem[];
    selectedCar: string;
    constructor() {
        this.cars = [
            {label: 'Audi', value: 'Audi'},
            {label: 'BMW', value: 'BMW'},
            {label: 'Fiat', value: 'Fiat'},
            {label: 'Ford', value: 'Ford'},
            {label: 'Honda', value: 'Honda'},
            {label: 'Jaguar', value: 'Jaguar'},
            {label: 'Mercedes', value: 'Mercedes'},
            {label: 'Renault', value: 'Renault'},
            {label: 'VW', value: 'VW'},
            {label: 'Volvo', value: 'Volvo'}
        ];
    }
}
 

Events

Styling

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

Dependencies

None.

Source

<h3 class="first">Basic</h3>
<p-listbox [options]="cities" [(ngModel)]="selectedCity"}" optionLabel="name"></p-listbox>
<p>Selected City: {{selectedCity ? selectedCity.name : 'none'}}</p>
<h3>Advanced (Multiple, Checkbox and Filter)</h3>
<p-listbox [options]="cities" [(ngModel)]="selectedCities" multiple="multiple" checkbox="checkbox" filter="filter" optionLabel="name">
  <p-header>
    <i class="fa fa-car"></i>
    Cars
  </p-header>
<p>Selected Cities: <span *ngFor="let c of selectedCities" style="margin-right: 10px">{{c.name}}</span></p>
<h3>Content</h3>
<p-listbox [options]="cars" [(ngModel)]="selectedCar" [listStyle]="{'max-height':'250px'}">
    <div class="ui-helper-clearfix">
      <img src="assets/showcase/images/demo/car/{{car.label}}.png" style="display:inline-block;margin:5px 0 0 5px" width="48">
      <span style="float:right;margin:20px 10px 0 0">{{car.value}}</span>
    </div>
  </ng-template>
  <p-footer>
    Selected: {{selectedCar||'none'}}
  </p-footer>
</p-listbox>
<button type="button" (click)="selectedCar=null" pButton icon="pi pi-times" label="Clear Selected Car"></button>
 

export class ListboxDemo {
    cities: City[];
    selectedCity: City;
    selectedCities: City[];
    cars: SelectItem[];
    selectedCar: string = 'BMW';
    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
        this.cars = [
            {label: 'Audi', value: 'Audi'},
            {label: 'BMW', value: 'BMW'},
            {label: 'Fiat', value: 'Fiat'},
            {label: 'Ford', value: 'Ford'},
            {label: 'Honda', value: 'Honda'},
            {label: 'Jaguar', value: 'Jaguar'},
            {label: 'Mercedes', value: 'Mercedes'},
            {label: 'Renault', value: 'Renault'},
            {label: 'VW', value: 'VW'},
            {label: 'Volvo', value: 'Volvo'}
        ];
    }