igx-simple-combo

March 24, 2026 · View on GitHub

The igx-simple-combo is a modification of the igx-combo component that allows single selection and has the appropriate UI and behavior for that. It inherits most of the igx-combo's API. It provides an editable input used for filtering data while also using the IgniteUI for Angular's igx-drop-down component to display the items in the data set. Alongside easy filtering and selection of a single item, the control provides grouping and adding of custom values to the data set. Templates can be provided in order to customize different areas of the components, such as items, header, footer, etc. Additionally, the control is integrated with the Template Driven and Reactive Forms. It also exposes intuitive keyboard navigation and it is accessibility compliant. Another thing worth mentioning is that the Drop Down items are virtualized, which guarantees smooth work, even if the control is bound to data source with a lot of items.

A walk through of how to get started can be found here

Usage

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

<igx-simple-combo [data]="localData" [valueKey]="'ProductID'" [displayKey]="'ProductName'"></igx-simple-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-simple-combo [data]="remoteData | async" (dataPreLoad)="dataLoading($event)" [valueKey]="'ProductID'" [displayKey]="'ProductName'" ></igx-simple-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 a 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-simple-combo [data]="myCustomData" valueKey="id" displayKey="text"></igx-simple-combo>

export class MyCombo {
    ...
    public combo: IgxSimpleComboComponent;
    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);
    }
}

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

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

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

Selection Events

The igx-simple-combo exposes both selectionChanging and selectionChanged.

selectionChanging is emitted before the selection is committed and can be canceled.
selectionChanged is emitted after the selection is committed and the component state is updated.
selectionChanged is not cancelable and always reports the final committed single selection state.

Value Binding

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

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

export class MyExampleComponent {
    ...
    public data: {text: string, id: number, ... }[] = ...;
    ...
    public value: 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 in a value to the combo that is the same as the unique identifier in the data set.

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

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

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

Filtering

Unlike the igx-combo, filtering in the igx-simple-combo is always enabled.

Custom Values

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

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

Disabled

You can disable the combo using the following code:

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

Disable Clear

You can hide the clear button using the following code:

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

When set to true, the clear button is not rendered even when a value is selected.

Grouping

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

<igx-simple-combo [groupKey]="'groupKey'"></igx-simple-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-simple-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-simple-combo>

Defining group headers template:

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

Defining header template:

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

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

Defining empty template:

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

Defining add template:

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

Defining toggle icon template:

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

Defining toggle icon template:

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

When the combo is closed and focused:

ArrowDown or Alt + ArrowDown will open the dropdown and will move focus to the selected item, if no selected item is present, the first item in the list will be focused.

When the combo is opened:

ArrowUp will close the dropdown if the search input is focused. If the active item is the first one in the list, the focus will be moved back to the search input while also selecting all of the text in the input. Otherwise ArrowUp will move to the previous list item.
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.
Alt + ArrowUp will close the dropdown.

When the combo is opened and a list item is focused:

End will move to last list item.
Home will move to first list item.
Space will select/deselect active list item without closing the dropdown.
Enter will confirm the currently focused item as selected and will close the dropdown.
Esc will close the dropdown.

When the combo 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 input and will select the new item.
ArrowUp will move the focus back to the last list item or if the list is empty will move it to the input.

Properties

Name	Description	Type
`id`	The combo's id.	`string`
`data`	The combo's data source.	`any[]`
`value`	The combo's value.	`any`
`selection`	The combo's selected item.	`any`
`allowCustomValue`	Enables/disables combo custom value.	`boolean`
`valueKey`	Determines which column in the data source is used to determine the value.	`string`
`displayKey`	Determines which column in the data source is used to determine the display value.	`string`
`groupKey`	The combo's 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`
`height`	Defines combo height.	`string`
`itemsMaxHeight`	Defines dropdown maximum height.	`number`
`itemsWidth`	Defines dropdown width.	`string`
`itemHeight`	Defines dropdown item height.	`number`
`placeholder`	Defines the "empty value" text.	`string`
`collapsed`	Gets the dropdown 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`
`valid`	gets if control is valid, when used in a form.	`boolean`
`overlaySettings`	Controls how the dropdown is displayed.	`OverlaySettings`
`selected`	Get current selection state.	`Array<any>`
`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[]`

Methods

Name	Description	Return type	Parameters
`open`	Opens dropdown	`void`	`None`
`close`	Closes dropdown	`void`	`None`
`toggle`	Toggles dropdown	`void`	`None`
`select`	Select a defined item	`void`	newItem: `any`
`deselect`	Deselect the currently selected item	`void`	`None`

Events

Name	Description	Cancelable	Parameters
`selectionChanging`	Emitted when item selection is changing, before the selection completes	true	{ oldValue: `any`, newValue: `any`, oldSelection: `any`, newSelection: `any`, displayText: `string`, owner: `IgxSimpleComboComponent` }
`selectionChanged`	Emitted after the selection completes and the component state has been updated	false	{ oldValue: `any`, newValue: `any`, oldSelection: `any`, newSelection: `any`, displayText: `string`, owner: `IgxSimpleComboComponent` }
`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	false	{ oldCollection: `Array<any>`, addedItem: `<any>`, newCollection: `Array<any>`, owner: `IgxSimpleComboComponent` }
`onDataPreLoad`	Emitted when new chunk of data is loaded from the virtualization	false	`IForOfState`
`opening`	Emitted before the dropdown is opened	true	`IBaseCancelableBrowserEventArgs`
`opened`	Emitted after the dropdown is opened	false	`IBaseEventArgs`
`closing`	Emitted before the dropdown is closed	true	`IBaseCancelableBrowserEventArgs`
`closed`	Emitted after the dropdown is closed	false	`IBaseEventArgs`

igx-simple-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

Properties

Methods

Events