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
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. IfvalueKey
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 fordisplayKey
, the combo will use the specifiedvalueKey
(if any). In our case, we want the combo to display thename
of each city and use theid
field for item selection and as the underlying value for each item. Therefore, we provide these properties to the combo'svalueKey
anddisplayKey
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
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.
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. |