Class IgcComboComponent<T>

The Combo component is similar to the Select component in that it provides a list of options from which the user can make a selection. In contrast to the Select component, the Combo component displays all options in a virtualized list of items, meaning the combo box can simultaneously show thousands of options, where one or more options can be selected. Additionally, users can create custom item templates, allowing for robust data visualization. The Combo component features case-sensitive filtering, grouping, complex data binding, dynamic addition of values and more.

Element

igc-combo

Slot

prefix - Renders content before the input.

Slot

suffix - Renders content after input.

Slot

header - Renders a container before the list of options.

Slot

footer - Renders a container after the list of options.

Slot

helper-text - Renders content below the input.

Slot

toggle-icon - Renders content inside the suffix container.

Slot

clear-icon - Renders content inside the suffix container.

Fires

igcFocus - Emitted when the select gains focus.

Fires

igcBlur - Emitted when the select loses focus.

Fires

igcChange - Emitted when the control's selection has changed.

Fires

igcOpening - Emitted just before the list of options is opened.

Fires

igcOpened - Emitted after the list of options is opened.

Fires

igcClosing - Emitter just before the list of options is closed.

Fires

igcClosed - Emitted after the list of options is closed.

Csspart

label - The encapsulated text label.

Csspart

input - The main input field.

Csspart

native-input - The native input of the main input field.

Csspart

prefix - The prefix wrapper.

Csspart

suffix - The suffix wrapper.

Csspart

toggle-icon - The toggle icon wrapper.

Csspart

clear-icon - The clear icon wrapper.

Csspart

case-icon - The case icon wrapper.

Csspart

helper-text - The helper text wrapper.

Csspart

search-input - The search input field.

Csspart

list-wrapper - The list of options wrapper.

Csspart

list - The list of options box.

Csspart

item - Represents each item in the list of options.

Csspart

group-header - Represents each header in the list of options.

Csspart

active - Appended to the item parts list when the item is active.

Csspart

selected - Appended to the item parts list when the item is selected.

Csspart

checkbox - Represents each checkbox of each list item.

Csspart

checkbox-indicator - Represents the checkbox indicator of each list item.

Csspart

checked - Appended to checkbox parts list when checkbox is checked.

Csspart

header - The container holding the header content.

Csspart

footer - The container holding the footer content.

Csspart

empty - The container holding the empty content.

Type Parameters

  • T extends object = any

Hierarchy

Hierarchy

  • FormRequiredInterface<this> & FormAssociatedElementInterface<this> & EventEmitterInterface<IgcComboEventMap, this> & LitElement<this>
    • IgcComboComponent

Constructors

Properties

autofocus: boolean

The autofocus attribute of the control.

Attr

autofocus

autofocusList: boolean = false

Focuses the list of options when the menu opens.

Attr

autofocus-list

caseSensitiveIcon: boolean = false

Enables the case sensitive search icon in the filtering input.

Attr

case-sensitive-icon

data: T[] = []

The data source used to generate the list of options.

disableFiltering: boolean = false

Disables the filtering of the list of options.

Attr

disable-filtering

disabled: boolean

The disabled state of the component

Attr

[disabled=false]

displayKey?: keyof T = ...

The key in the data source used to display items in the list.

Attr

display-key

groupHeaderTemplate: ComboItemTemplate<T> = ...

The template used for the content of each combo group header.

groupKey?: keyof T = ...

The key in the data source used to group items in the list.

Attr

group-key

groupSorting: GroupingDirection = 'asc'

Sorts the items in each group by ascending or descending order.

Attr

group-sorting

invalid: boolean

Control the validity of the control.

Attr

itemTemplate: ComboItemTemplate<T> = ...

The template used for the content of each combo item.

label: string

The label attribute of the control.

Attr

label

name: string

The name attribute of the control.

Attr

open: boolean = false

Sets the open state of the component.

Attr

open

outlined: boolean = false

The outlined attribute of the control.

Attr

outlined

placeholder: string

The placeholder attribute of the control.

Attr

placeholder

placeholderSearch: string = 'Search'

The placeholder attribute of the search input.

Attr

placeholder-search

required: boolean

Makes the control a required field in a form context.

Attr

singleSelect: boolean = false

Enables single selection mode and moves item filtering to the main input.

Attr

single-select

valueKey?: keyof T

The key in the data source used when selecting items.

Attr

value-key

styles: CSSResult[] = ...
tagName: "igc-combo" = 'igc-combo'

Accessors

  • get form(): null | HTMLFormElement
  • Returns the HTMLFormElement associated with this element.

    Returns null | HTMLFormElement

  • get validationMessage(): string
  • A string containing the validation message of this element.

    Returns string

  • get validity(): ValidityState
  • Returns a ValidityState object which represents the different validity states the element can be in, with respect to constraint validation.

    Returns ValidityState

  • get value(): ComboValue<T>[]
  • Returns the current selection as a list of comma separated values, represented by the value key, when provided.

    Returns ComboValue<T>[]

  • set value(items): void
  • Sets the value (selected items). The passed value must be a valid JSON array. If the data source is an array of complex objects, the valueKey attribute must be set. Note that when displayKey is not explicitly set, it will fall back to the value of valueKey.

    Attr

    value

    Example

    <igc-combo
    .data=${[
    {
    id: 'BG01',
    name: 'Sofia'
    },
    {
    id: 'BG02',
    name: 'Plovdiv'
    }
    ]}
    display-key='name'
    value-key='id'
    value='["BG01", "BG02"]'>
    </igc-combo>

    Parameters

    • items: ComboValue<T>[]

    Returns void

  • get willValidate(): boolean
  • A boolean value which returns true if the element is a submittable element that is a candidate for constraint validation.

    Returns boolean

Methods

  • Removes focus from the component.

    Returns void

  • Checks for validity of the control and emits the invalid event if it invalid.

    Returns boolean

  • Returns void

  • Deselects option(s) in the list by either reference or valueKey. If not argument is provided all items will be deselected.

    Example

    const combo<IgcComboComponent<T>> = document.querySelector('igc-combo');

    // Deselect one item at a time by reference when valueKey is not specified.
    combo.deselect(combo.data[0]);

    // Deselect multiple items at a time by reference when valueKey is not specified.
    combo.deselect([combo.data[0], combo.data[1]]);

    // Deselect one item at a time when valueKey is specified.
    combo.deselect('BG01');

    // Deselect multiple items at a time when valueKey is specified.
    combo.deselect(['BG01', 'BG02']);

    Parameters

    • Optional items: Item<T> | Item<T>[]

      One or more items to be deselected. Multiple items should be passed as an array. When valueKey is specified, the corresponding value should be used in place of the item reference.

    Returns void

  • Type parameters

    Type Parameters

    Parameters

    • type: K
    • Optional eventInitDict: CustomEventInit<D>

    Returns boolean

  • Sets focus on the component.

    Parameters

    • Optional options: FocusOptions

    Returns void

  • Checks for validity of the control and shows the browser message if it invalid.

    Returns boolean

  • Selects option(s) in the list by either reference or valueKey. If not argument is provided all items will be selected.

    Example

    const combo<IgcComboComponent<T>> = document.querySelector('igc-combo');

    // Select one item at a time by reference when valueKey is not specified.
    combo.select(combo.data[0]);

    // Select multiple items at a time by reference when valueKey is not specified.
    combo.select([combo.data[0], combo.data[1]]);

    // Select one item at a time when valueKey is specified.
    combo.select('BG01');

    // Select multiple items at a time when valueKey is specified.
    combo.select(['BG01', 'BG02']);

    Parameters

    • Optional items: Item<T> | Item<T>[]

      One or more items to be selected. Multiple items should be passed as an array. When valueKey is specified, the corresponding value should be used in place of the item reference.

    Returns void

  • Sets a custom validation message for the control. As long as message is not empty, the control is considered invalid.

    Parameters

    • message: string

    Returns void