Combo
The Ignite UI for Angular Combo is a component that combines an input field with a searchable dropdown list, letting users filter the options by typing and select one or more items.
The Angular Combo is the igx-combo component. It shows its options in a virtualized dropdown list and supports filtering, grouping, custom values, and two-way binding with Angular forms.
Live Demo
Anatomy
The Combo combines an input field with a searchable dropdown list, letting users filter the options by typing and select one or more items.
2. Label (optional): text that describes what the user should select
3. Left Icon(optional): an optional leading icon that adds context to the field
4. Hint Text: helper text shown below the field for extra guidance
5. Placeholder Text: default text shown when no value is selected
6. Toggle: used to open or close the options list
7. Search Input: allows users to filter the list by typing
8. Dropdown Header: used to group or describe the dropdown options
9. Selected Item: selected Item from the Dropdown List
10. Dropdown List: displays the list of selectable options
The igx-combo element renders its input field in an input group and its dropdown list in an overlay:
igx-combo
├─ igx-input-group
│ ├─ [igxLabel]
│ ├─ igx-prefix
│ ├─ input[igxInput][role="combobox"] // read-only, shows the selected items
│ ├─ igx-suffix.igx-combo__clear-button // shown when the Combo has a value
│ ├─ igx-suffix.igx-combo__toggle-button
│ └─ igx-hint
└─ igx-combo-drop-down // the dropdown, shown in an overlay
└─ div.igx-drop-down__list-scroll[role="listbox"]
└─ div.igx-combo
├─ div.igx-combo__search // hidden with disableFiltering
│ └─ input[igxInput][role="searchbox"]
├─ [igxComboHeader] template
├─ div.igx-combo__content // the options
│ └─ igx-combo-item[role="option"] // role="group" for the group headers
├─ div.igx-combo__add // the empty message and the add item button
│ └─ igx-combo-add-item[role="button"] // shown with allowCustomValues
└─ [igxComboFooter] template
Getting Started
To use the Angular Combo, follow the Ignite UI for Angular Getting Started topic for the basic project setup, then add the component for your target platform.
If your project doesn’t use Ignite UI for Angular yet, run ng add igniteui-angular. Then import the IGX_COMBO_DIRECTIVES token and add it to the imports of your component. The token holds the IgxComboComponent and its template directives:
import { Component } from '@angular/core';
import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular/combo';
// import { IGX_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular/combo'; for licensed package
@Component({
selector: 'app-home',
template: `
<igx-combo [data]="cities" valueKey="id" displayKey="name" placeholder="Cities"></igx-combo>
`,
imports: [IGX_COMBO_DIRECTIVES]
})
export class HomeComponent {
public cities = [
{ id: 'BG01', name: 'Sofia' },
{ id: 'BG02', name: 'Plovdiv' },
{ id: 'BG03', name: 'Varna' }
];
}
Usage
Use the Angular Combo when users pick one or more options from a long list and need to search it, such as a list of cities or countries.
Type (Material Theme)
In the Material theme, the Combo Input provides selection between a border type for a more structured perception on solid color backgrounds, and a boxed type that is most appropriate when placed on top of a vivid image to improve readability. The Bootstrap, Fluent, and Indigo themes draw both types the same way, so the other samples of this topic show the box type only in the Material theme.
The Angular Combo uses the box type by default. Set the type input to border for the border type. Add the label with the igxLabel directive and the left icon with an igx-prefix:
<!-- Border type -->
<igx-combo type="border" placeholder="Select a value" [data]="options">
<label igxLabel>Label</label>
<igx-prefix><igx-icon>language</igx-icon></igx-prefix>
</igx-combo>
<!-- Box type -->
<igx-combo type="box" placeholder="Select a value" [data]="options">
<label igxLabel>Label</label>
</igx-combo>
Disabled States
Set disabled on the Angular Combo to show the disabled state of both the border and the box type.
<igx-combo type="border" [disabled]="true" placeholder="Country" [data]="countries"></igx-combo>
Size
The Combo is available in three sizes: Large, Medium and Small. The Dropdown automatically adjusts its dimensions to match the selected size variant. Set the size with the --ig-size CSS variable:
.small {
--ig-size: var(--ig-size-small);
}
.large {
--ig-size: var(--ig-size-large);
}
Interaction States
The Combo component supports five states for the enabled variants: Idle, Idle & Hover, Filled, Filled & Hover and Focused, as well as three validation states: Success, Warn, and Error.
Clicking the input field or the toggle opens the dropdown. To open and close the dropdown in code, use the open, close, and toggle methods:
@ViewChild(IgxComboComponent, { static: true })
public combo: IgxComboComponent;
public openCombo(): void {
this.combo.open();
}
The following sample shows the states side by side. Hover and focus come from the pointer and the keyboard, so the sample turns on the hover and the focus styles of the theme for its display-only combos.
Validation States
Every experienced designer uses constraints wisely to limit the user input and avoid invalid states, hence the availability of validation styles. Through the available validation styles, the Combo Input is consistent with the standard Input and equipped for sophisticated designs that display success, warn, and error visuals.
The Angular Combo takes its validation state from the form control that it is bound to, through ngModel or a reactive form. Set the valid property to an IgxInputState value to set the state in code. The Angular Combo has no warn state of its own, so the sample shows it with the warning style of its input group. Put the guidance or the error message in an igx-hint:
<igx-combo type="border" [data]="countries" valueKey="id" displayKey="name" [(ngModel)]="selection" required>
<igx-hint>Please select a different region</igx-hint>
</igx-combo>
Dropdown Size
The Dropdown used for the Combo comes with the appropriate sizing for Large, Medium and Small Combo similarly to the normal Dropdown component. The dropdown takes its size from the Combo, so set the --ig-size variable on the Combo.
The Angular Combo also exposes the itemHeight and itemsMaxHeight inputs for the height of the items and of the list:
<igx-combo [data]="countries" [itemHeight]="40" [itemsMaxHeight]="160"></igx-combo>
The following sample shows the dropdowns only, without their input fields.
Dropdown Search Input
The dropdown of the Angular Combo contains a search input that filters the options as users type.
Set the text of the empty search input with the igx_combo_filter_search_placeholder entry of resourceStrings, show a button that toggles case-sensitive filtering with showSearchCaseIcon, and hide the search input with disableFiltering. The filteringOptions input sets the key that the search filters by and whether the filtering is case-sensitive:
<igx-combo [data]="cities" displayKey="name" [resourceStrings]="{ igx_combo_filter_search_placeholder: 'Search cities' }" [showSearchCaseIcon]="true"
[filteringOptions]="{ filteringKey: 'name', caseSensitive: false }">
</igx-combo>
The following sample shows the search input only. Hover and focus come from the pointer and the keyboard, so the sample turns on the hover and the focus styles of the theme for its display-only search inputs.
Data Binding
The Angular Combo builds its list of options from the array that you bind to data. When the array holds objects, set the keys that the Combo uses:
valueKey- the field that identifies an option. The value and the selection of the Combo use it. When you omit it, the Combo uses references to the objects.displayKey- the field that the list and the input field show. When you omit it, the Combo uses thevalueKey.groupKey- the field that groups the options. Each group gets a header, andgroupSortingDirectionsorts the groups. See Grouping in the Combo Features topic.
To bind to data that loads from a remote service, see Remote Binding in the Combo Features topic.
When the array holds primitive values, such as strings or numbers, don’t set the valueKey and the displayKey. The Combo uses the values themselves.
Value and Selection
The Angular Combo exposes its selected items through its value, and methods that select and deselect items in code.
The Angular Combo supports two-way binding with [(ngModel)] and works in template-driven and reactive forms. The selection property returns the selected items, and the select, deselect, selectAllItems, and deselectAllItems methods change it:
<igx-combo [data]="cities" displayKey="name" valueKey="id" [(ngModel)]="selectedCities"></igx-combo>
export class CitiesComponent {
@ViewChild(IgxComboComponent, { static: true })
public combo: IgxComboComponent;
public selectedCities: string[] = ['BG01', 'UK01'];
public selectFavorites(): void {
this.combo.select(['UK01', 'BG01']);
}
}
The Angular Combo emits selectionChanging before the selection changes, which you can cancel, and selectionChanged after the selection is committed.
To let users select a single item and type in the input field, use the Simple Combo.
Do/Don’t
When using the Combo, its input and dropdown should have the same width and their left and right borders should match. Regarding how the dropdown is shown when the Combo is focused, you should always show it on top of the content that follows the Combo triggering its display. Combos don’t push content like expansion panels do.
Align the dropdown with the input so both have the same width and matching left and right borders.
Avoid a dropdown that is narrower than the input or shifted out of alignment, as it breaks the visual connection between the two.
Properties
The Angular Combo exposes the following properties. See the API reference for the complete type definitions.
| Name | Type | Default | Description |
|---|---|---|---|
data |
any[] |
— | The options of the Combo. |
valueKey |
string |
— | The field that identifies an option. |
displayKey |
string |
— | The field that the list and the input field show. Falls back to the valueKey. |
groupKey |
string |
— | The field that groups the options. |
type |
IgxInputGroupType |
'box' |
The type of the input field: box, border, or line. |
placeholder |
string |
— | The text that the input field shows when no item is selected. |
resourceStrings |
IComboResourceStrings |
— | The texts of the Combo, including the one that the empty search input shows. |
disabled |
boolean |
false |
Whether the Combo is disabled. |
disableFiltering |
boolean |
false |
Whether the search input is hidden. |
showSearchCaseIcon |
boolean |
false |
Whether the search input shows the button that toggles case-sensitive filtering. |
filteringOptions |
IComboFilteringOptions |
— | The key that the search filters by and whether the filtering is case-sensitive. |
allowCustomValues |
boolean |
false |
Whether users can add the text of the search input as a new item. |
disableClear |
boolean |
false |
Whether the clear button is hidden. |
autoFocusSearch |
boolean |
true |
Whether the search input takes the focus when the dropdown opens. |
itemHeight |
number |
— | The height of the items in the list. |
itemsMaxHeight |
number |
— | The maximum height of the list. |
valid |
IgxInputState |
INITIAL |
The validation state of the Combo. |
selection |
any[] |
— | Read-only. The selected items. |
Methods
The Angular Combo exposes the following methods.
| Method | Description |
|---|---|
select |
Selects the items that you pass. Pass true as the second argument to clear the current selection first. |
deselect |
Deselects the items that you pass. |
selectAllItems |
Selects all items. Pass true to ignore the current filter. |
deselectAllItems |
Deselects all items. Pass true to ignore the current filter. |
open |
Opens the dropdown. |
close |
Closes the dropdown. |
toggle |
Opens the dropdown when it is closed, and closes it when it is open. |
Events
The Angular Combo emits the following events.
| Name | Description |
|---|---|
selectionChanging |
Emitted with IComboSelectionChangingEventArgs before the selection changes. Set cancel to keep the selection. |
selectionChanged |
Emitted with IComboSelectionChangedEventArgs after the selection is committed. |
opening |
Emitted before the dropdown opens. Cancelable. |
opened |
Emitted after the dropdown opens. |
closing |
Emitted before the dropdown closes. Cancelable. |
closed |
Emitted after the dropdown closes. |
searchInputUpdate |
Emitted when the text of the search input changes. |
addition |
Emitted before users add a custom value to the list. |
Styling
The Combo comes with the combined styling flexibility of its input and dropdown pieces. There are options for the input text elements’ color, border style and color. For the dropdown one may change the background color, or use the various options related to the items in the Combo Dropdown, such as the Search Input and the items with their background and text colors.
Change the colors of the toggle and the clear buttons of the Angular Combo with the following CSS variables:
| Variable | What it changes |
|---|---|
--ig-combo-toggle-button-background |
The background of the toggle button. |
--ig-combo-toggle-button-foreground |
The icon color of the toggle button. |
--ig-combo-toggle-button-foreground-filled |
The icon color of the toggle button when the Combo has a value. |
--ig-combo-toggle-button-background-focus |
The background of the toggle button when the Combo is focused. |
--ig-combo-toggle-button-foreground-focus |
The icon color of the toggle button when the Combo is focused. |
--ig-combo-toggle-button-background-disabled |
The background of the toggle button when the Combo is disabled. |
--ig-combo-toggle-button-foreground-disabled |
The icon color of the toggle button when the Combo is disabled. |
--ig-combo-clear-button-background |
The background of the clear button. |
--ig-combo-clear-button-foreground |
The icon color of the clear button. |
--ig-combo-search-separator-border-color |
The color of the line between the search input and the list. |
--ig-combo-empty-list-placeholder-color |
The color of the text that the empty list shows. |
The input field takes its colors from the --ig-input-group-* variables, the dropdown from the --ig-drop-down-* variables, and the checkboxes of the items from the --ig-checkbox-* variables, so you can set all of them on the Combo.
Sass Theming
When you modify a primary property, all related dependent properties are automatically updated to reflect the change. The primary parameter of the combo-theme function is $toggle-button-background, from which the theme derives the colors of the toggle button in all states. Create the themes of the Combo, its dropdown, and its checkboxes, and include them with the tokens() mixin, which emits the matching CSS variables in the scope where you include it.
@use "igniteui-angular/theming" as *;
$custom-combo-theme: combo-theme(
$toggle-button-background: #e0e0e0
);
$custom-drop-down-theme: drop-down-theme(
$background-color: #e6f2ff
);
$custom-checkbox-theme: checkbox-theme(
$fill-color: #005dcc,
$empty-color: #005dcc
);
:host {
@include tokens($custom-combo-theme);
@include tokens($custom-drop-down-theme);
@include tokens($custom-checkbox-theme);
}
The Angular Combo shows its dropdown in an overlay. Depending on the view encapsulation and on where the overlay outlet is, a theme included under :host may not reach the dropdown. See the Overlay Styling topic.
CSS Variables
Set the CSS variables on a Combo or on a container when you need local styling without a Sass build step:
.styled-combo {
--ig-input-group-border-color: #1377d5;
--ig-combo-toggle-button-background: #e0e0e0;
--ig-drop-down-background-color: #e6f2ff;
--ig-drop-down-selected-item-background: #4ca7e3;
--ig-checkbox-fill-color: #005dcc;
}
Styling with Tailwind
You can style the Angular Combo using our custom Tailwind utility classes. Make sure to set up Tailwind first.
Import the Ignite UI utilities in your global stylesheet:
@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";
Use the light-combo or dark-combo class for the corresponding theme, and override the generated CSS variables with arbitrary properties:
<igx-combo class="!light-combo ![--toggle-button-background:#e5ebf3] ![--clear-button-foreground:#212121]">
...
</igx-combo>
The exclamation mark (!) gives the Tailwind utility precedence over the default theme styles of the Combo.
Accessibility
The Angular Combo uses the roles of the WAI-ARIA combobox pattern: the input field is a combobox that controls a listbox of options, and users open the list, move through it, and select options with the keyboard.
Keyboard Interaction
The input field of the Angular Combo is a tab stop. The following keys work while the Combo has the focus:
| Key | Action |
|---|---|
| Arrow Down / Alt + Arrow Down | In the closed Combo, opens the dropdown and moves the focus to the search input. In the search input, moves the focus to the first option, or to the add item button when the list is empty and custom values are allowed. In the list, moves to the next option, and from the last option to the add item button when it is shown. |
| Arrow Up / Alt + Arrow Up | In the search input, closes the dropdown and moves the focus to the Combo. In the list, moves to the previous option. From the first option, moves the focus back to the search input, or closes the dropdown and moves the focus to the Combo when there is no search input. |
| Home / End | In the list, moves to the first or the last option. |
| Space | In the list, selects or deselects the active option. |
| Enter | In the list, confirms the selection and closes the dropdown. On the add item button, adds the text of the search input as a new item and selects it. |
| Escape | When the dropdown is open, closes it and keeps the focus on the Combo. When the dropdown is closed, clears the selection. |
| Tab | Closes the dropdown and moves the focus to the next focusable element. |
Screen Readers / ARIA
The Angular Combo renders the following roles and attributes:
| Element | Role | Attributes |
|---|---|---|
| The input of the input field | combobox |
aria-haspopup="listbox", aria-expanded, aria-controls that points to the list, aria-labelledby, and aria-label |
| The search input | searchbox |
aria-autocomplete="list" and aria-label="search" |
| The dropdown | listbox |
aria-labelledby that points to the igxLabel or to the ariaLabelledBy element |
| The container of the options | — | aria-multiselectable="true" and aria-activedescendant that points to the active option |
| Each option | option |
aria-selected |
| Each group header | group |
— |
| The add item button | button |
aria-label from the resource strings |
The input field takes its accessible name from the igxLabel or from the ariaLabelledBy input. Without them, it gets a name from the resource strings that says whether options are selected.
Accessibility Compliance
Infragistics documents Ignite UI for Angular accessibility support for Section 508 and WCAG 2.1 guideline areas in the Accessibility Compliance topic.
| Criterion | How the component complies |
|---|---|
| 1.3.1 Info and Relationships | The combobox, listbox, and option roles expose the structure, and the list is labeled by the igxLabel or the ariaLabelledBy element. |
| 2.1.1 Keyboard | The arrow keys open the dropdown and move through the options, and Space selects the active option. |
| 2.1.2 No Keyboard Trap | Tab closes the dropdown and moves the focus out of the Combo. |
| 4.1.2 Name, Role, Value | The input field exposes the combobox role, a name from the label, and its expanded state through aria-expanded. Each option exposes its selected state through aria-selected. |
Your responsibilities:
- Give every Combo a label that names what users select. See Type.
- When you override the theme colors, keep a contrast ratio of at least 3:1 for the borders and the focus indicator, as 1.4.11 Non-text Contrast requires.
- Show the error message in the helper text, not by color alone. See Validation States.
Known Limitations
- The input field that shows the selected items isn’t editable. In Firefox, the cursor is visible in it.
- When the Angular Combo is bound to an array of primitives that contains
undefined, the list doesn’t showundefined. When thevalueKeyfield of an object isundefined, the list shows the item, but users can’t select it. - When the Angular Combo is bound to a remote service and has a predefined selection, the input field stays blank until the data loads.
- The list uses the Virtual Scroll, so its limitations apply. The list renders only the options in view, and code that queries the DOM finds only those options.
API References
Dependencies
The Angular Combo requires a theme to apply its colors and sizes. See the framework-specific setup in Getting Started.
The Angular Combo uses the Drop Down, the Input Group, the Checkbox, the Icon, and the Overlay. Their themes style its parts:
Additional Resources
The following resources provide more Angular Combo guidance and project support:
Related Components
The Angular Combo lets users search a list and select one or more options. Use these components when the selection works differently:
- Select - Use Select when users pick a single option from a short list that doesn’t need search.
- Dropdown - Use Dropdown to show a list of actions or options from a button or another element.
- Simple Combo - Use Simple Combo when users select a single item and can type in the input field to filter the list or enter a custom value.
FAQ
These questions cover common Angular Combo setup, selection, and usage scenarios.
Bind the Angular Combo with [(ngModel)] or a form control to an array of valueKey values, or call the select method with the items. Without a valueKey, the Angular Combo uses references to the objects in its data.
The Angular Combo always allows multiple selection. Use the Simple Combo when users must select a single item; it also lets users type in the input field to filter the list.
Set the groupKey of the Angular Combo to the field that holds the group of each option. The Angular Combo shows a header for each group and sorts the groups.
Use the Angular Combo when the list is long, users need to search it, or they select more than one option. Use the Angular Select for a short list from which users pick a single option without searching.