igx-combo

March 24, 2026 · View on GitHub

The igx-combo component provides a powerful input, combining the features of the basic HTML input, select and the IgniteUI for Angular igx-drop-down components. The combo component provides easy filtering and selection of multiple items, grouping and adding custom values to the dropdown list. Custom templates could be provided in order to customize different areas of the components, such as items, header, footer, etc. The combo component is integrated with the Template Driven and Reactive Forms. The igx-combo exposes intuitive keyboard navigation and it is accessibility compliant. Drop Down items are virtualized, which guarantees smooth work, even if the igx-combo is bound to data source with a lot of items.

igx-combo is a component. A walkthrough of how to get started can be found here

Usage

Basic usage of igx-combo bound to a local data source, defining valueKey and displayKey:

<igx-combo [data]="localData" [valueKey]="'ProductID'" [displayKey]="'ProductName'"></igx-combo>

Remote binding, defining valueKey and displayKey, and exposing dataPreLoad that allows to load new chunk of remote data to the combo (see the sample above as a reference):

<igx-combo [data]="remoteData | async" (dataPreLoad)="dataLoading($event)" [valueKey]="'ProductID'" [displayKey]="'ProductName'" ></igx-combo>

public ngOnInit(): void {
    this.remoteData = this.remoteService.remoteData;
}

public ngAfterViewInit(): void {
    this.remoteService.getData(this.combo.virtualizationState, (data) => {
        this.combo.totalItemCount = data.length;
    });
}

public dataLoading(evt): void {
        if (this.prevRequest) {
            this.prevRequest.unsubscribe();
        }

        this.prevRequest = this.remoteService.getData(this.combo.virtualizationState, () => {
            this.cdr.detectChanges();
            this.combo.triggerCheck();
        });
    }

Note: In order to have combo with remote data, what you need is to have a service that retrieves data chunks from a server. What the combo exposes is a virtualizationState property that gives state of the combo - first index and the number of items that needs to be loaded. The service, should inform the combo for the total items that are on the server - using the totalItemCount property.

Features

Selection

Combo selection depends on the [valueKey] input property:

If a [valueKey] is specified, all methods and events tied to the selection operate w/ the value key property of the combo's [data] items:

    <igx-combo [data]="myCustomData" valueKey="id" displayKey="text"></igx-combo>

export class MyCombo {
    ...
    public combo: IgxComboComponent;
    public myCustomData: { id: number, text: string } = [{ id: 0, name: "One" }, ...];
    ...
    public ngOnInit(): void {
        // Selection is done only by valueKey property value
        this.combo.select([0, 1]);
    }
}

When no valueKey is specified, selection is handled by equality (===). To select items by object reference, the valueKey property should be removed:

    <igx-combo [data]="myCustomData" displayKey="text"></igx-combo>

export class MyCombo {
    public ngOnInit(): void {
        this.combo.select([this.data[0], this.data[1]]);
    }
}

Selection Events

The igx-combo exposes both selectionChanging and selectionChanged.

selectionChanging is emitted before a new selection state is committed and can be canceled.
If selectionChanging is not canceled, the component commits the final selection state and then emits selectionChanged.
selectionChanged is emitted after the selection completes and the component state is updated.
selectionChanged is not cancelable and reports the final committed selection state.

Value Binding

If we want to use a two-way data-binding, we could just use ngModel like this:

<igx-combo #combo [data]="data" valueKey="id" displayKey="text" [(ngModel)]="values"></igx-combo>

export class MyExampleComponent {
    ...
    public data: {text: string, id: number, ... }[] = ...;
    ...
    public values: number[] = ...;
}

When the data input is made up of complex types (i.e. objects), it is advised to bind the selected data via valueKey (as in the above code snippet). Specify a property that is unique for each data entry and pass an array with values for those properties, corresponding to the items you want selected.

If you want to bind the selected data by reference, do not specify a valueKey:

<igx-combo #combo [data]="data" displayKey="text" [(ngModel)]="values"></igx-combo>

export class MyExampleComponent {
    ...
    public data: {text: string, id: number, ... }[] = ...;
    ...
    public values: {text: string, id: number, ...} [] = [this.items[0], this.items[5]];
}

Filtering

By default filtering in the combo is enabled. However you can disable it using the following code:

<igx-combo [filterable]="false"></igx-combo>

You can enable search case sensitivity by setting the showSearchCaseIcon property to true

<igx-combo [showSearchCaseIcon]="true"></igx-combo>

Custom Values

Enabling the custom values will add missing from the list, using the combo's interface.

<igx-combo [allowCustomValues]="true"></igx-combo>

Disabled

You can disable combo using the following code:

<igx-combo [disabled]="true"></igx-combo>

Disable Clear

You can hide the clear button using the following code:

<igx-combo [disableClear]="true"></igx-combo>

When set to true, the clear button is not rendered even when items are selected.

Grouping

Defining a combo's groupKey option will group the items, according to that key.

<igx-combo [groupKey]="'primaryKey'"></igx-combo>

Templates

Templates for different parts of the control can be defined, including items, header and footer, etc. When defining one of them, you need to reference list of predefined names, as follows:

Defining item template:

<igx-combo>
	<ng-template igxComboItem let-display let-key="valueKey">
		<div class="item">
			<span class="state">State: {{ display[key] }}</span>
			<span class="region">Region: {{ display.region }}</span>
		</div>
	</ng-template>
</igx-combo>

Defining group headers template:

<igx-combo>
    <ng-template igxComboHeaderItem let-headerItem let-key="groupKey">
        <div class="group-header-class">
            Header for {{ headerItem[key] }}
        </div>
    </ng-template>
</igx-combo>

Defining header template:

<igx-combo>
    <ng-template igxComboHeader>
        <div class="header-class">Custom header</div>
        <img src=""/>
    </ng-template>
</igx-combo>

<igx-combo>
    <ng-template igxComboFooter>
        <div class="footer-class">Custom footer</div>
        <img src=""/>
    </ng-template>
</igx-combo>

Defining empty template:

<igx-combo>
    <ng-template igxComboEmpty>
        <span>List is empty</div>
    </ng-template>
</igx-combo>

Defining add template:

<igx-combo>
    <ng-template igxComboAddItem>
        <span>Add town</span>
    </ng-template>
</igx-combo>

Defining toggle icon template:

<igx-combo>
    <ng-template igxComboToggleIcon let-collapsed>
        <igx-icon>{{ collapsed ? 'remove_circle' : 'remove_circle_outline'}}</igx-icon>
    </ng-template>
</igx-combo>

Defining toggle icon template:

<igx-combo>
    <ng-template igxComboClearIcon>
        <igx-icon>clear</igx-icon>
    </ng-template>
</igx-combo>

When igxCombo is closed and focused:

ArrowDown or Alt + ArrowDown will open the combo drop down and will move focus to the search input.

When igxCombo is opened and search input is focused:

ArrowUp or Alt + ArrowUp will close the combo drop down and will move focus to the closed combo.
ArrowDown will move focus from the search input to the first list item.If list is empty and custom values are enabled will move it to the Add new item button.

Note: Any other key stroke will be handled by the input.

When igxCombo is opened and list item is focused:

ArrowDown will move to next list item. If the active item is the last one in the list and custom values are enabled then focus will be moved to the Add item button.
ArrowUp will move to previous list item. If the active item is the first one in the list then focus will be moved back to the search input.
End will move to last list item.
Home will move to first list item.
Space will select/deselect active list item.
Enter will confirm the already selected items and will close the list.
Esc will close the list.

When igxCombo is opened, allow custom values are enabled and add item button is focused:

Enter will add new item with valueKey and displayKey equal to the text in the search input and will select the new item.
ArrowUp focus will be moved back to the last list item or if list is empty will be moved to the search input.

API

Inputs

Name	Description	Type
`id`	combo id	string
`data`	combo data source	any[]
`allowCustomValue`	enables/disables combo custom value	boolean
`filterable`	enables/disables combo drop down filtering - enabled by default	boolean
`showSearchCaseIcon`	defines whether the search case-sensitive icon should be displayed - disabled by default	boolean
`valueKey`	combo value data source property	string
`displayKey`	combo display data source property	string
`groupKey`	combo item group	string
`virtualizationState`	defines the current state of the virtualized data. It contains `startIndex` and `chunkSize`	`IForOfState`
`totalItemCount`	total count of the virtual data items, when using remote service	number
`width`	defines combo width	string
`itemsMaxHeight`	defines drop down maximum height	number
`itemsWidth`	defines drop down width	string
`itemHeight`	defines drop down item height	number
`placeholder`	defines the "empty value" text	string
`searchPlaceholder`	defines the placeholder text for search input	string
`collapsed`	gets drop down state	boolean
`disabled`	defines whether the control is active or not	boolean
`disableClear`	defines whether the clear button is rendered	boolean
`ariaLabelledBy`	defines label ID related to combo	string
`type`	Combo style. - "line", "box", "border", "search"	string
`valid`	gets if control is valid, when used in a form	boolean
`overlaySettings`	gets/sets the custom overlay settings that control how the drop-down list displays	OverlaySettings
`autoFocusSearch`	controls whether the search input should be focused when the combo is opened	boolean
`filteringOptions`	Configures the way combo items will be filtered	IComboFilteringOptions
`filterFunction`	Gets/Sets the custom filtering function of the combo	`(collection: any[], searchValue: any, caseSensitive: boolean) => any[]`

Getters

Name	Description	Type
`displayValue`	the value of the combo text field	string
`value`	the value of the combo	any[]
`selection`	the selected items of the combo	any[]

Outputs

Name	Description	Cancelable	Emitted with
`selectionChanging`	Emitted when item selection is changing, before the selection completes	true	`IComboSelectionChangingEventArgs`
`selectionChanged`	Emitted after the selection completes and the component state has been updated	false	`IComboSelectionChangedEventArgs`
`searchInputUpdate`	Emitted when an the search input's input event is triggered	true	`IComboSearchInputEventArgs`
`addition`	Emitted when an item is being added to the data collection	true	`IComboItemAdditionEvent`
`dataPreLoad`	Emitted when new chunk of data is loaded from the virtualization	false	`IForOfState`
`opening`	Emitted before the dropdown is opened	false	`IBaseCancelableBrowserEventArgs`
`opened`	Emitted after the dropdown is opened	false	`IBaseEventArgs`
`closing`	Emitted before the dropdown is closed	false	`IBaseCancelableBrowserEventArgs`
`closed`	Emitted after the dropdown is closed	false	`IBaseEventArgs`

Methods

Name	Description	Return type	Parameters
`open`	Opens drop down	`void`	`None`
`close`	Closes drop down	`void`	`None`
`toggle`	Toggles drop down	`void`	`None`
`selectedItems`	Get current selection state	`any[]`	`None`
`select`	Select defined items	`void`	items: `any[]`, clearCurrentSelection: `boolean`
`deselect`	Deselect defined items	`void`	items: `any[]`
`selectAllItems`	Select all (filtered) items	`void`	ignoreFilter?: `boolean` - if `true` selects all values
`deselectAllItems`	Deselect (filtered) all items	`void`	ignoreFilter?: `boolean` - if `true` deselects all values
`selected`	Toggles (select/deselect) an item by key	`void`	itemID: any, select = true, event?: Event

igx-combo

Usage

Features

Selection

Selection Events

Value Binding

Filtering

Custom Values

Disabled

Disable Clear

Grouping

Templates

Defining item template:

Defining group headers template:

Defining header template:

Defining footer template:

Defining empty template:

Defining add template:

Defining toggle icon template:

Defining toggle icon template:

Keyboard Navigation

API

Inputs

Getters

Outputs

Methods