Class IgxComboComponent

Represents a drop-down list that provides editable functionalities, allowing users to choose an option from a predefined list.

Igx Module

IgxComboModule

Igx Theme

igx-combo-theme

Igx Keywords

combobox, combo selection

Igx Group

Grids & Lists

Remarks

It provides the ability to filter items as well as perform selection with the provided data. Additionally, it exposes keyboard navigation and custom styling capabilities.

Example

<igx-combo [itemsMaxHeight]="250" [data]="locationData"
[displayKey]="'field'" [valueKey]="'field'"
placeholder="Location(s)" searchPlaceholder="Search...">
</igx-combo>

Hierarchy

Hierarchy

  • IgxComboBaseDirective
    • IgxComboComponent

Implements

  • AfterViewInit
  • ControlValueAccessor
  • OnInit
  • OnDestroy
  • DoCheck
  • EditorProvider

Constructors

Properties

addItemTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering the ADD BUTTON in the combo drop down

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.addItemTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboAddItem>
<button class="combo__add-button">
Click to add item
</button>
</ng-template>
</igx-combo>
addition: EventEmitter<IComboItemAdditionEvent> = ...

Emitted when an item is being added to the data collection

<igx-combo (addition)='handleAdditionEvent($event)'></igx-combo>
allowCustomValues: boolean = false

Controls whether custom values can be added to the collection

// get
let comboAllowsCustomValues = this.combo.allowCustomValues;
<!--set-->
<igx-combo [allowCustomValues]='true'></igx-combo>
ariaLabelledBy: string

An

Input

property that set aria-labelledby attribute

<igx-combo [ariaLabelledBy]="'label1'">
autoFocusSearch: boolean = true

An

Input

property that controls whether the combo's search box should be focused after the opened event is called When false, the combo's list item container will be focused instead

clearIconTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering the combo CLEAR button

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.clearIconTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboClearIcon>
<igx-icon>clear</igx-icon>
</ng-template>
</igx-combo>
closed: EventEmitter<IBaseEventArgs> = ...

Emitted after the dropdown is closed

<igx-combo (closed)='handleClosed($event)'></igx-combo>
closing: EventEmitter<IBaseCancelableBrowserEventArgs> = ...

Emitted before the dropdown is closed

<igx-combo (closing)='handleClosing($event)'></igx-combo>
dataPreLoad: EventEmitter<IForOfState> = ...

Emitted when new chunk of data is loaded from the virtualization

<igx-combo (dataPreLoad)='handleDataPreloadEvent($event)'></igx-combo>
densityChanged: EventEmitter<IDensityChangedEventArgs> = ...
disabled: boolean = false

An

Input

property that enabled/disables combo. The default is false.

<igx-combo [disabled]="'true'">
emptyTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering the ADD BUTTON in the combo drop down

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.emptyTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboEmpty>
<div class="combo--empty">
There are no items to display
</div>
</ng-template>
</igx-combo>
filterFunction: ((collection: any[], searchValue: any, filteringOptions: IComboFilteringOptions) => any[])

Type declaration

    • (collection: any[], searchValue: any, filteringOptions: IComboFilteringOptions): any[]
    • Gets/Sets the custom filtering function of the combo.

      Example

       <igx-comb #combo [data]="localData" [filterFunction]="filterFunction"></igx-combo>
      

      Parameters

      Returns any[]

footerTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering the FOOTER for the combo items list

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.footerTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboFooter>
<div class="combo__footer">
This is a custom footer
</div>
</ng-template>
</igx-combo>
headerItemTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering HEADER ITEMS for groups in the combo list

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.headerItemTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboHeaderItem let-item let-key="groupKey">
<div class="custom-item--group">Group header for {{ item[key] }}</div>
</ng-template>
</igx-combo>
headerTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering the HEADER for the combo items list

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.headerTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboHeader>
<div class="combo__header">
This is a custom header
</div>
</ng-template>
</igx-combo>
id: string = ...

Gets/gets combo id.

// get
let id = this.combo.id;
<!--set-->
<igx-combo [id]='combo1'></igx-combo>
itemTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering ITEMS in the combo list

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.itemTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboItem let-item let-key="valueKey">
<div class="custom-item">
<div class="custom-item__name">{{ item[key] }}</div>
<div class="custom-item__cost">{{ item.cost }}</div>
</div>
</ng-template>
</igx-combo>
itemsWidth: string

Configures the drop down list width

// get
let myComboItemsWidth = this.combo.itemsWidth;
<!--set-->
<igx-combo [itemsWidth] = '"180px"'></igx-combo>
opened: EventEmitter<IBaseEventArgs> = ...

Emitted after the dropdown is opened

<igx-combo (opened)='handleOpened($event)'></igx-combo>
opening: EventEmitter<IBaseCancelableBrowserEventArgs> = ...

Emitted before the dropdown is opened

<igx-combo opening='handleOpening($event)'></igx-combo>
overlaySettings: OverlaySettings = null

Set custom overlay settings that control how the combo's list of items is displayed. Set:

<igx-combo [overlaySettings] = "customOverlaySettings"></igx-combo>
 const customSettings = { positionStrategy: { settings: { target: myTarget } } };
combo.overlaySettings = customSettings;

Get any custom overlay settings used by the combo:

 const comboOverlaySettings: OverlaySettings = myCombo.overlaySettings;
placeholder: string

Defines the placeholder value for the combo value field

// get
let myComboPlaceholder = this.combo.placeholder;
<!--set-->
<igx-combo [placeholder]='newPlaceHolder'></igx-combo>
searchInputUpdate: EventEmitter<IComboSearchInputEventArgs> = ...

Emitted when the value of the search input changes (e.g. typing, pasting, clear, etc.)

<igx-combo (searchInputUpdate)='handleSearchInputEvent($event)'></igx-combo>
searchPlaceholder: string = 'Enter a Search Term'

Defines the placeholder value for the combo dropdown search field

// get
let myComboSearchPlaceholder = this.combo.searchPlaceholder;
<!--set-->
<igx-combo [searchPlaceholder]='newPlaceHolder'></igx-combo>
selectionChanging: EventEmitter<IComboSelectionChangingEventArgs> = ...

Emitted when item selection is changing, before the selection completes

<igx-combo (selectionChanging)='handleSelection()'></igx-combo>
showSearchCaseIcon: boolean = false

Defines whether the caseSensitive icon should be shown in the search input

// get
let myComboShowSearchCaseIcon = this.combo.showSearchCaseIcon;
<!--set-->
<igx-combo [showSearchCaseIcon]='true'></igx-combo>
toggleIconTemplate: TemplateRef<any> = null

The custom template, if any, that should be used when rendering the combo TOGGLE(open/close) button

// Set in typescript
const myCustomTemplate: TemplateRef<any> = myComponent.customTemplate;
myComponent.combo.toggleIconTemplate = myCustomTemplate;
<!-- Set in markup -->
<igx-combo #combo>
...
<ng-template igxComboToggleIcon let-collapsed>
<igx-icon>{{ collapsed ? 'remove_circle' : 'remove_circle_outline'}}</igx-icon>
</ng-template>
</igx-combo>
valueKey: string = null

Determines which column in the data source is used to determine the value.

// get
let myComboValueKey = this.combo.valueKey;
<!--set-->
<igx-combo [valueKey]='myKey'></igx-combo>
width: string

Sets the style width of the element

// get
let myComboWidth = this.combo.width;
<!--set-->
<igx-combo [width]='250px'></igx-combo>

Accessors

  • get groupKey(): string
  • The item property by which items should be grouped inside the items list. Not usable if data is not of type Object[].

    // get
    let currentGroupKey = this.combo.groupKey;

    Returns string

  • set groupKey(val: string): void
  • The item property by which items should be grouped inside the items list. Not usable if data is not of type Object[].

    <!--set-->
    <igx-combo [groupKey]='newGroupKey'></igx-combo>

    Parameters

    • val: string

    Returns void

  • get totalItemCount(): number
  • Gets total count of the virtual data items, when using remote service.

    // get
    let count = this.combo.totalItemCount;

    Returns number

  • set totalItemCount(count: number): void
  • Sets total count of the virtual data items, when using remote service.

    // set
    this.combo.totalItemCount(remoteService.count);

    Parameters

    • count: number

    Returns void

Methods

  • Deselect defined items

    Parameters

    • items: any[]

      items to deselected

      this.combo.deselect(["New York", "New Jersey"]);
      
    • Optional event: Event

    Returns void

  • Deselect all (filtered) items

    Parameters

    • Optional ignoreFilter: boolean

      if set to true, deselects all items, otherwise deselects only the filtered ones.

      this.combo.deselectAllItems();
      
    • Optional event: Event

    Returns void

  • Select defined items

    Parameters

    • newItems: any[]

      new items to be selected

    • Optional clearCurrentSelection: boolean

      if true clear previous selected items

      this.combo.select(["New York", "New Jersey"]);
      
    • Optional event: Event

    Returns void

  • Select all (filtered) items

    Parameters

    • Optional ignoreFilter: boolean

      if set to true, selects all items, otherwise selects only the filtered ones.

      this.combo.selectAllItems();
      
    • Optional event: Event

    Returns void

  • Selects/Deselects a single item

    Parameters

    • itemID: any

      the itemID of the specific item

    • select: boolean = true

      If the item should be selected (true) or deselected (false)

      Without specified valueKey;

      this.combo.valueKey = null;
      const items: { field: string, region: string}[] = data;
      this.combo.setSelectedItem(items[0], true);

      With specified valueKey;

      this.combo.valueKey = 'field';
      const items: { field: string, region: string}[] = data;
      this.combo.setSelectedItem('Connecticut', true);
    • Optional event: Event

    Returns void