React ComboBox Overview

    React 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 React ComboBox keyboard navigation, templates to customize how the items, header, and footer are displayed.

    The Ignite UI for React 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.

    React ComboBox Example

    EXAMPLE
    TSX
    CSS

    Like this sample? Get access to our complete Ignite UI for React toolkit and start building your own apps in minutes. Download it for free.

    Getting Started with React ComboBox

    First, you need to the install the corresponding Ignite UI for React npm package by running the following command:

    npm install igniteui-react
    cmd

    You will then need to import the React ComboBox, its necessary CSS, and register its module, like so:

    import { IgrComboModule, IgrCombo } from 'igniteui-react';
    import 'igniteui-webcomponents/themes/light/bootstrap.css';
    
    IgrComboModule.register();
    tsx

    The IgrCombo component doesn't work with the standard <form> element. Use Form 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" },
    ];
    
    <IgrCombo
        valueKey="id"
        displayKey="name"
        data={cities}
        value={["BG01"]}
    ></IgrCombo>
    tsx

    Data value and display properties

    When 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 item selection. The component exposes the following properties:

    • valueKey - Optional, required for complex data object - 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.
    • displayKey - Optional, recommended for complex data objects - 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). In our case, we want the combo to display the name of each city and use the id field for item selection and as the underlying value for each item. Therefore, we provide these properties to the combo's valueKey and displayKey respectively.

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

    Setting Value

    The ComboBox component exposes a value getter and setter in addition to an attribute, which is also called value. You can use the value attribute to set the selected items on component initialization.

    If you want to read the value, i.e. the list of currently selected items, or to update the value use the value getter and setter respectively. The value getter will return a list of all selected items as represented by the valueKey. Likewise, if you want to update the list of selected items by using the value setter, you should provide a list of items by their valueKey.

    Example:

    const comboRef = useRef<IgrCombo>(null);
    
    // Given the overview example from above this will return ['BG01']
    console.log(comboRef.current.value);
    
    // Change the selected items to New York and London
    comboRef.current.value = ['NY01', 'UK01'];
    tsx

    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'
    comboRef.current.select(["UK01", "UK02", "UK03", "UK04", "UK05"]);
    comboRef.current.deselect(["UK01", "UK02", "UK03", "UK04", "UK05"]);
    tsx

    Select/deselect all items:

    // Select/deselect all items
    comboRef.current.select([]);
    comboRef.current.deselect([]);
    tsx

    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
    comboRef.current.select([cities[1], cities[5]]);
    comboRef.current.deselect([cities[1], cities[5]]);
    tsx

    EXAMPLE
    DATA
    TSX
    CSS

    Validation

    The Ignite UI for React Combo component supports most of the IgrInput 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.
    Ignite UI for React | CTA Banner

    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 React ComboBox

    You can change the appearance of the Ignite UI for React IgrCombo 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.

    EXAMPLE
    DATA
    TSX
    CSS

    API Reference

    Additional Resources