Web Components ComboBox Overview

    Web Components ComboBox is a lightweight editor that enables users to easily select, filter, and group different predefined options in a provided list. The component also supports options for Web Components ComboBox keyboard navigation, templates to customize how the items, header, and footer are displayed.

    The Ignite UI for Web Components ComboBox component provides a list of options from which users can make a selection. It displays all options in a virtualized list of items, meaning the ComboBox can simultaneously show thousands of records, where one or more options can be selected. Additionally, the component features case-sensitive filtering, grouping, complex data binding and more.

    Web Components ComboBox Example

    Getting Started with Web Components ComboBox

    First, you need to install the Ignite UI for Web Components by running the following command:

    npm install igniteui-webcomponents
    

    Before using the ComboBox component, you need to register it together with its additional components:

    import { defineComponents, IgcComboComponent }
    from 'igniteui-webcomponents';
    import 'igniteui-webcomponents/themes/light/bootstrap.css';
    
    defineComponents(IgcComboComponent);
    
    Warning

    The IgcComboComponent component doesn't work with the standard <form> element. Use IgcFormComponent instead.

    Then, we will bind an array of objects to the combo data source used for building the list of options.

    interface City {
        id: string;
        name: string;
    }
    
    const cities: City[] = [
        { name: 'London', id: 'UK01' },
        { name: 'Sofia', id: 'BG01'},
        { name: 'New York', id: 'NY01'}
    ];
    
    export class Sample {
        private combo: IgcComboComponent<City>;
    
        constructor() {
            this.combo = document.getElementById('basic-combo') as IgcComboComponent<City>;
            this.combo.data = cities;
        }
    }
    
    <igc-combo id="basic-combo" display-key="name" value-key="id"></igc-combo>
    

    Data value and display properties

    Since the combo is bound to a list of complex data (i.e. objects), we need to specify a property that the control will use to handle the selected items. The component exposes the following properties:

    • displayKey - Optional, required for object arrays - Determines which field in the data source is used as the display value. If no value is specified for displayKey, the combo will use the specified valueKey (if any).
    • valueKey - Optional, recommended for object arrays - Determines which field of the data source will be used to make selections. If valueKey is omitted, the selection API will use object references to select items.

    In our case, we want the combo to display the name of each city and use the id field for item selection. Therefore, we provide these properties to the combo's displayKey and valueKey respectively.

    Note

    When the data source consists of a primitive types (e.g. strings, numbers, etc.), do not specify a valueKey and displayKey.

    Selection API

    The combo component exposes APIs that allow you to change the currently selected items.

    Besides selecting items from the list of options by user interaction, you can select items programmatically. This is done via the select and deselect methods. You can pass an array of items to both methods. If the methods are called with no arguments all items will be selected/deselected depending on which method is called. If you have specified a valueKey for your combo component, then you should pass the value keys of the items you would like to select/deselect:

    Select/deselect some items:

    // Select/deselect items by their IDs as valueKey is set to 'id'
    combo.select(['BG01', 'BG02', 'BG03', 'BG04']);
    combo.deselect(['BG01', 'BG02', 'BG03', 'BG04']);
    

    Select/deselect all items:

    // Select/deselect all items
    combo.select();
    combo.deselect();
    

    If the valueKey property is omitted, you will have to list the items you wish to select/deselect as objects references:

    // Select/deselect values by object references when no valueKey is provided
    combo.select([cities[1], cities[5]]);
    combo.deselect([cities[1], cities[5]]);
    

    Validation

    The Ignite UI for Web Components Combo component supports most of the IgcInputComponent properties, such as required, disabled, autofocus, invalid, etc. The component also exposes two methods bound to its validation:

    • reportValidity() - checks for validity and returns true if the component satisfies the validation constraints.
    • checkValidity() - a wrapper around reportValidity to comply with the native input API.

    Keyboard Navigation

    When the combo component is focused and the list of options is not visible:

    • Open the list of options using Down/Alt + Down keys.

    When the combo component is focused and the list of options is visible:

    • Using the Down key will activate the next item in the list.
    • Using the Up key will activate the previous item in the list. If the first item is already active it will focus the input.
    • Using the Home or End keys will activate the first or the last item in the list.
    • Using the Space key will select the active item.
    • Using the Enter key will select the active item and close the list of options.
    • Using the Esc or Tab/Shift + Tab keys will close the list of options.

    Styling Web Components ComboBox

    You can change the appearance of the Ignite UI for Web Components IgcComboComponent component and its items, by using the exposed CSS parts listed below:

    CSS Parts

    Part name Description
    label The encapsulated text label.
    input The main input field.
    native-input The native input of the main input field.
    prefix The prefix wrapper.
    suffix The suffix wrapper.
    toggle-icon The toggle icon wrapper.
    clear-icon The clear icon wrapper.
    case-icon A case-icon wrapper that renders content inside the suffix of the filter-input.
    helper-text The helper text wrapper.
    search-input The search input field.
    list-wrapper The list of options wrapper.
    list The list of options box.
    item Represents each item in the list of options.
    group-header Represents each header in the list of options.
    active Appended to the item parts list when the item is active.
    selected Appended to the item parts list when the item is selected.
    checkbox Represents each checkbox of each list item.
    checkbox-indicator Represents the checkbox indicator of each list item.
    checked Appended to checkbox parts list when checkbox is checked.
    header The container holding the header content.
    footer The container holding the footer content.
    empty The container holding the empty content.

    API Reference

    Additional Resources