Infragistics
Close
Angular React Web Components Blazor Angular
Open Source

Combo Templates

The Ignite UI for Angular Combo Templates replace the default content of the Combo areas: the items, the group headers, the header and the footer of the list, the empty list, the toggle and the clear icons, and the input field.

The Angular Combo takes each template as an ng-template element with one of its template directives, placed inside the igx-combo element. The directives come with the IGX_COMBO_DIRECTIVES token, as the Combo topic shows, together with the igxLabel, igx-prefix, igx-suffix, and igx-hint elements that template the input field.

Live Demo

The sample shows a Destinations combo with cities grouped by region. Each switch applies one template to the combo, and the Selection list below the combo shows the selected cities.

Types

The Angular Combo has a template for each area that it renders. Reference each template through its directive, and read the item and the keys of the Combo from the template context.

The snippets bind the Combo to destinations that have an id, a name, a country, a countryCode, a region, and a UTC offset, with id as the valueKey, name as the displayKey, and region as the groupKey.

Item Template

The item template renders the content of each option in the list. By default, an option shows its displayKey value, and the checkbox of the option stays in front of the template content.

Use the igxComboItem directive. The template receives the item as its implicit value, together with the valueKey, the displayKey, and the data of the Combo:

<igx-combo [data]="destinations" valueKey="id" displayKey="name" groupKey="region">
    <ng-template igxComboItem let-destination let-key="displayKey">
        <span class="destination">
            <img class="flag" [src]="'https://dl.infragistics.com/x/img/flags/' + destination.countryCode + '.png'" alt="" />
            {{ destination[key] }} — {{ destination.country }} · {{ destination.id }} · {{ destination.offset }}
        </span>
    </ng-template>
</igx-combo>

Header Item Template

The header item template renders the header of each group when the Combo has a groupKey. By default, a group header shows the group value. The template receives a header record, not a data item: its groupKey field holds the group value, so a count of the options in the group comes from the data of the Combo, as the citiesIn method of the snippets does.

Use the igxComboHeaderItem directive. The template receives the header record as its implicit value, together with the groupKey, the valueKey, the displayKey, and the data of the Combo:

<igx-combo [data]="destinations" valueKey="id" displayKey="name" groupKey="region">
    <ng-template igxComboHeaderItem let-header let-key="groupKey">
        <span class="region">
            <strong>{{ header[key] }}</strong>
            <span class="region-count">{{ citiesIn(header[key]) }} cities</span>
        </span>
    </ng-template>
</igx-combo>

Header Template

The header template renders content between the search input and the list of options, such as a title of the list or an action that applies to it. The Combo renders no header by default.

Use the igxComboHeader directive. The snippet adds a button that selects the options that the search input shows, through the selectAllItems method:

<igx-combo #combo [data]="destinations" valueKey="id" displayKey="name" groupKey="region">
    <ng-template igxComboHeader>
        <div class="list-header">
            <span>Destinations by region</span>
            <button igxButton="flat" (click)="combo.selectAllItems()">Select all</button>
        </div>
    </ng-template>
</igx-combo>

The footer template renders content below the list of options, such as a summary of the selection or an action that applies to it. The Combo renders no footer by default.

Use the igxComboFooter directive. The snippet shows the number of selected items from the selection property, and clears the selection through the deselectAllItems method:

<igx-combo #combo [data]="destinations" valueKey="id" displayKey="name" groupKey="region">
    <ng-template igxComboFooter>
        <div class="list-footer">
            <span>{{ combo.selection.length }} selected</span>
            <button igxButton="flat" (click)="combo.deselectAllItems()">Clear</button>
        </div>
    </ng-template>
</igx-combo>

Empty Template

The empty template renders in place of the list when the search text matches no option, or when the Combo has no data. By default, the Combo shows a message that the list is empty.

Use the igxComboEmpty directive. The template has no context, so read the search text from the searchValue property of the Combo through a template reference. When allowCustomValues is set, the add item stays below the empty content:

<igx-combo #combo [data]="destinations" valueKey="id" displayKey="name" [allowCustomValues]="true">
    <ng-template igxComboEmpty>
        <span class="empty-list">No city matches "{{ combo.searchValue }}". Add it below, or try another spelling.</span>
    </ng-template>
</igx-combo>

Add Template

The add template renders the add item that the Angular Combo shows below the empty list content when allowCustomValues is set and the search text matches no option. By default, the add item is a button with an “Add item” label. Clicking the add item, or pressing Enter on it, emits the cancelable addition event, adds an item whose valueKey and displayKey fields hold the search text, and selects it.

Use the igxComboAddItem directive, and read the search text from the searchValue property through a template reference:

<igx-combo #combo [data]="destinations" valueKey="id" displayKey="name" [allowCustomValues]="true">
    <ng-template igxComboAddItem>
        <button igxButton="outlined">Add "{{ combo.searchValue }}" as a destination</button>
    </ng-template>
</igx-combo>

Toggle Icon Template

The toggle icon template replaces the icon of the toggle button in the input field, which opens and closes the dropdown.

Use the igxComboToggleIcon directive. The template also receives whether the dropdown is collapsed as its implicit value, for an icon that changes with the state. Register the icon first, as the Icon topic shows:

<igx-combo [data]="destinations" valueKey="id" displayKey="name">
    <ng-template igxComboToggleIcon>
        <igx-icon family="material" name="flight"></igx-icon>
    </ng-template>
</igx-combo>

Clear Icon Template

The clear icon template replaces the icon of the clear button in the input field. The Combo shows the clear button only when it has a selection.

Use the igxComboClearIcon directive:

<igx-combo [data]="destinations" valueKey="id" displayKey="name">
    <ng-template igxComboClearIcon>
        <igx-icon>close</igx-icon>
    </ng-template>
</igx-combo>

Templated Input

The input field of the Combo takes a label, content before and after its text, and a helper text below it, the way the Input Group does.

Add the label with the igxLabel directive, the content before and after the text with the igx-prefix and igx-suffix elements, and the helper text with the igx-hint element. The suffix content renders before the clear and the toggle buttons:

<igx-combo #combo [data]="destinations" valueKey="id" displayKey="name" placeholder="Pick one or more cities">
    <label igxLabel>Destinations</label>
    <igx-prefix><igx-icon>place</igx-icon></igx-prefix>
    <igx-suffix><igx-badge [value]="combo.selection.length"></igx-badge></igx-suffix>
    <igx-hint>{{ combo.selection.length }} of {{ destinations.length }} destinations selected</igx-hint>
</igx-combo>

API References

Additional Resources

The following resources provide more Angular Combo guidance and project support: