Angular Listbox

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

Setup

Refer to PrimeNG setup documentation for download and installation steps for your environment.

Import

import {ListboxModule} from 'primeng/listbox';

Getting Started

Listbox requires a value to bind and a collection of options.

<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name"></p-listbox>

interface City {
    name: string,
    code: string
}

export class ListboxDemo {

    cities: City[];

    selectedCity: City;

    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
    }

}

Value Binding

The option itself is bound to the model by default, use optionValue to customize the property to pass as the value.

<p-listbox [options]="cities" [(ngModel)]="selectedCityCode" optionLabel="name" optionValue="code"></p-listbox>

interface City {
    name: string,
    code: string
}

export class ListboxDemo {

    cities: City[];

    selectedCityCode: string;

    constructor() {
        this.cities = [
            {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" [multiple]="true" optionLabel="name"></p-listbox>

export class ListboxDemo {

    cities: City[];

    selectedCities: City[];

    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY'},
            {name: 'Rome', code: 'RM'},
            {name: 'London', code: 'LDN'},
            {name: 'Istanbul', code: 'IST'},
            {name: 'Paris', code: 'PRS'}
        ];
    }

}

Disabled Options

Particular options can be prevented from selection using the optionDisabled property.

<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name" optionDisabled="inactive"></p-listbox>

export class ListboxDemo {

    cities: City[];

    selectedCity: City;

    constructor() {
        this.cities = [
            {name: 'New York', code: 'NY', inactive: false},
            {name: 'Rome', code: 'RM', inactive: true},
            {name: 'London', code: 'LDN', inactive: false},
            {name: 'Istanbul', code: 'IST', inactive: true},
            {name: 'Paris', code: 'PRS', inactive: false}
        ];
    }

}

Filter

Filtering allows searching items in the list using an input field at the header. In order to use filtering, set filter property as true. Default filtering mode is "contains" and alternatives are available via the filterMatchMode property. See property documentation for more information.

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

Model Driven Forms

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

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

Custom Content

For custom content support define a ng-template named item where the local ng-template variable refers to an option in the options collection. Additionally a custom header and footer can be provided using header and footer templates. In addition when grouping is enabled, group template is available to customize the option groups. All templates get the option instance as the default local template variable.

<p-listbox [options]="countries" [(ngModel)]="selectedCountries" [multiple]="true" optionLabel="name" [listStyle]="{'max-height':'250px'}">
    <ng-template pTemplate="header">
        Header Content
    </ng-template>
    <ng-template let-country pTemplate="item">
        <div class="country-item">
            <img src="assets/showcase/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + country.code.toLowerCase()" />
            <div>{{country.name}}</div>
        </div>
    </ng-template>
    <ng-template pTemplate="footer">
        Footer Content
    </ng-template>
</p-listbox>

interface Country {
    name: string,
    code: string
}

export class ListboxDemo {

    countries: Country[];

    selectedCountries: Country[];

    constructor() {
        this.countries = [
            {name: 'Australia', code: 'AU'},
            {name: 'Brazil', code: 'BR'},
            {name: 'China', code: 'CN'},
            {name: 'Egypt', code: 'EG'},
            {name: 'France', code: 'FR'},
            {name: 'Germany', code: 'DE'},
            {name: 'India', code: 'IN'},
            {name: 'Japan', code: 'JP'},
            {name: 'Spain', code: 'ES'},
            {name: 'United States', code: 'US'}
        ];
    }

}

Theming

Listbox supports various themes featuring Material, Bootstrap, Fluent as well as your own custom themes via the Designer tool.

Resources

Visit the PrimeNG Listbox showcase for demos and documentation.