Input - Listbox - 《PrimeNG Document》

Documentation
Source

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

Documentation

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

Updating Options

When itemLabel property is used, Listbox does not detect changes in the options so provide a new reference when you need to update the options such as adding a new option.


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

Disabled Options

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

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">
    <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".
filterValue	string	null	When specified, filter displays with this value.
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.
ariaFilterLabel	string	null	Defines a string that labels the filter input.

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.
onClick	event.originalEvent: browser event event.value: single value that are clicked	Callback to invoke when listbox option clicks.

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.

Source

View on GitHub


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