DEV Community

loading...
Cover image for Angular Listbox

Angular Listbox

primetek profile image PrimeTek ・3 min read

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';
Enter fullscreen mode Exit fullscreen mode

Getting Started

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

<p-listbox [options]="cities" [(ngModel)]="selectedCity" optionLabel="name"></p-listbox>
Enter fullscreen mode Exit fullscreen mode
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'}
        ];
    }

}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode
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'}
        ];
    }

}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode
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'}
        ];
    }

}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode
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}
        ];
    }

}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Model Driven Forms

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

<p-listbox [options]="cities" formControlName="selectedCity"></p-listbox>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode
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'}
        ];
    }

}
Enter fullscreen mode Exit fullscreen mode

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.

Discussion (0)

pic
Editor guide