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

Basic

Selected City: {{selectedCity ? selectedCity.name : 'none'}}

Advanced (Multiple, Checkbox and Filter)

Cars

Selected Cities: {{c.name}}

Content

{{car.value}}
Selected: {{selectedCar||'none'}}

Import


import {ListboxModule} from 'primeng/listbox';

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>



import {SelectItem} from 'primeng/api';

export class MyModel {

    cities: SelectItem[];

    selectedCities: string[];

    constructor() {
        this.cities = [
            {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'}}
        ];
    }

}

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

Label of an option is used as the display text of an item by default, for custom content support define a ng-template where the local ng-template variable refers to an option in the options collection. Additionally a custom header and footer can be provided using p-header and p-footer element.


<p-listbox [options]="cars" [(ngModel)]="selectedCar" [style]="{'width':'190px'}">
    <p-header>
      <i class="fa fa-car"></i>
      List of Car
    </p-header>
    <ng-template let-car let-i="index" pTemplate="item">
        <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">{{i}} - {{car.value}}</span>
        </div>
    </ng-template>
    <p-footer>
        Selected: {{selectedCar||'none'}}
    </p-footer>
</p-listbox>



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'}
        ];
    }
}

Properties

Name Type Default Description
options array null An array of selectitems to display as the available options.
optionLabel string null Name of the label field of an option when an arbitrary objects instead of SelectItems are used as options.
multiple boolean false When specified, allows selecting multiple values.
checkbox boolean false When specified, allows selecting items with checkboxes.
filter boolean false When specified, displays a filter input at header.
filterMode string contains Defines how the items are filtered, valid values are "contains" (default) and "startsWith".
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.
style string null Inline style of the container.
styleClass string null Style class of the container.
listStyle string null Inline style 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.
dataKey string null A property to uniquely identify a value in options.
showToggleAll boolean true Whether header checkbox is shown in multiple mode.

Events

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: Clicked selecte item 		Callback to invoke when an item is double clicked.

Styling

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

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

Dependencies

None.

 View on GitHub 

<h3 class="first">Basic</h3>
<p-listbox [options]="cities" [(ngModel)]="selectedCity" [style]="{'width':'200px'}" 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-listbox>
<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" [style]="{'width':'190px'}" [listStyle]="{'max-height':'250px'}">
  <ng-template let-car pTemplate="item">
    <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="fa-close" 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'}
        ];
    }
}