diff --git a/docs/angular/src/content/en/components/angular-reactive-form-validation.mdx b/docs/angular/src/content/en/components/angular-reactive-form-validation.mdx index 749ac30399..6dd2d66a84 100644 --- a/docs/angular/src/content/en/components/angular-reactive-form-validation.mdx +++ b/docs/angular/src/content/en/components/angular-reactive-form-validation.mdx @@ -182,7 +182,7 @@ export class MyComponent implements OnInit { Related topics: -- [Combo](/combo) +- [Combo](/inputs/combo/overview) - [Select](/select) - [Input Group](/input-group) - [Date Picker](/date-picker) diff --git a/docs/angular/src/content/en/components/combo-features.mdx b/docs/angular/src/content/en/components/combo-features.mdx index a1d9570546..098878c5da 100644 --- a/docs/angular/src/content/en/components/combo-features.mdx +++ b/docs/angular/src/content/en/components/combo-features.mdx @@ -227,12 +227,12 @@ Additional components and/or directives with relative APIs that were used:
-- [ComboBox Component](/combo) +- [ComboBox Component](/inputs/combo/overview) - [ComboBox Remote Binding](/combo-remote) -- [ComboBox Templates](/combo-templates) +- [ComboBox Templates](/inputs/combo/templates) - [Template Driven Forms Integration](/input-group) - [Reactive Forms Integration](/angular-reactive-form-validation) -- [Single Select ComboBox](/simple-combo) +- [Single Select ComboBox](/inputs/combo/single-selection) Our community is active and always welcoming to new ideas. diff --git a/docs/angular/src/content/en/components/combo-remote.mdx b/docs/angular/src/content/en/components/combo-remote.mdx index 401d31c32e..dd38953068 100644 --- a/docs/angular/src/content/en/components/combo-remote.mdx +++ b/docs/angular/src/content/en/components/combo-remote.mdx @@ -227,7 +227,7 @@ A service needs to be included as a provider. ### Handling Selection -When using a combobox bound to remote data loaded in chunks and dealing with a more complex data type (e.g. objects), it is necessary to define a `valueKey`. As stated in the [combobox topic](/combo#data-value-and-display-properties), when no `valueKey` is specified, the combobox will try to handle selection by `equality (===)`. Since the objects that will be marked as selected will not be the same as the object that are continuously loaded, the selection will fail. +When using a combobox bound to remote data loaded in chunks and dealing with a more complex data type (e.g. objects), it is necessary to define a `valueKey`. As stated in the [combobox topic](/inputs/combo/overview#data-binding), when no `valueKey` is specified, the combobox will try to handle selection by `equality (===)`. Since the objects that will be marked as selected will not be the same as the object that are continuously loaded, the selection will fail. When binding a combobox to remote data, make sure to specify a `valueKey`, representing a property that is unique to each item. @@ -243,12 +243,12 @@ When the combobox is bound to remote data, setting value/selected items through
-- [ComboBox Component](/combo) +- [ComboBox Component](/inputs/combo/overview) - [ComboBox Features](/combo-features) -- [ComboBox Templates](/combo-templates) +- [ComboBox Templates](/inputs/combo/templates) - [Template Driven Forms Integration](/input-group) - [Reactive Forms Integration](/angular-reactive-form-validation) -- [Single Select ComboBox](/simple-combo) +- [Single Select ComboBox](/inputs/combo/single-selection) Our community is active and always welcoming to new ideas. diff --git a/docs/angular/src/content/en/components/combo-templates.mdx b/docs/angular/src/content/en/components/combo-templates.mdx deleted file mode 100644 index 6bbf09f852..0000000000 --- a/docs/angular/src/content/en/components/combo-templates.mdx +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: ComboBox Templates - MIT license -description: Custom templates for different areas of the igx-combo component can be defined, including items, header, footer, empty list and adding button. -keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Angular Combo components, Angular Templates, Angular Combo Templates -license: MIT -llms: - description: "The Ignite UI for Angular ComboBox Component allows defining custom templates for different areas such as header, footer, items, empty list and adding button." ---- - -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; -import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; - -# ComboBox Templates - -
- -The Ignite UI for Angular ComboBox Component allows defining custom templates for different areas such as header, footer, items, empty list and adding button. -
- -## Angular ComboBox Templates Example - - - -## Usage - -To get started with the ComboBox component, first you need to import the `IgxComboModule` in your **app.module.ts** file: - -```typescript -import { IgxComboModule } from 'igniteui-angular/combo'; -// import { IgxComboModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - imports: [ - ... - IgxComboModule, - ... - ] -}) -export class AppModule {} -``` - -## Template Types - -When defining combobox templates, you need to reference them using the following predefined reference names: - -### Item template - -Use selector `[igxComboItem]`: - -```html - - -
- - {{ display[key] }} - {{ display.region }} - -
- - -``` - - -### Header Item template - -Use selector `[igxComboHeaderItem]`: - -```html - - -
-Region: {{ display[key] }} -
- - -``` - -### Header template - -Use selector `[igxComboHeader]`: - -```html - - -
-State - Region -
- - -``` - -### Footer template - -Use selector `[igxComboFooter]`: - -```html - - -
-Infragistics 2018 -
- - -``` - -### Empty template - -Use selector `[igxComboEmpty]`: - -```html - - - No available states - - -``` - -### Add template - -Use selector `[igxComboAddItem]`: - -```html - - - - - -``` - -### Toggle Icon Template - -Use selector `[igxComboToggleIcon]`: - -```html - - - {{ collapsed ? 'expand_more' : 'expand_less'}} - - -``` - - -This component uses Material Icons. Add the following link to your `index.html`: `` - - -### Clear Icon Template - -Use selector `[igxComboClearIcon]`: - -```html - - - cancel - - -``` - -## Templating ComboBox Input - -When used with templates, the `igxComboClearIcon` and the `igxComboToggleIcon` selectors, change how the respective buttons appear in the combobox input. Passing content inside of the `igx-combo` also allows templating of the combobox input similar to the way an `igx-input-group` can be templated (using `igx-prefix`, `igx-suffix` and `igxLabel`). The code snippet below illustrates how to add an appropriate label and prefix to the combobox input: - -```html - - - pin_drop - -``` - -## API References -
-- -- -## Additional Resources - -
- -- [ComboBox Component](/combo) -- [ComboBox Features](/combo-features) -- [ComboBox Remote Binding](/combo-remote) -- [Template Driven Forms Integration](/input-group) -- [Reactive Forms Integration](/angular-reactive-form-validation) -- [Single Select ComboBox](/simple-combo) - -Our community is active and always welcoming to new ideas. - -- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/combo.mdx b/docs/angular/src/content/en/components/combo.mdx deleted file mode 100644 index 7f127f9b65..0000000000 --- a/docs/angular/src/content/en/components/combo.mdx +++ /dev/null @@ -1,464 +0,0 @@ ---- -title: Angular Combobox Component | Data binding combobox | Infragistics | MIT license -description: The Ignite UI for Angular ComboBox provides a powerful input, combining features of the basic HTML input, select, filtering and custom drop-down lists. Try it for FREE -keywords: angular combobox, angular combo component, angular combobox component, Angular UI Components, ignite ui for angular, infragistics -license: MIT -llms: - description: "The Angular ComboBox component represents a drop-down list that provides editable functionalities, allowing users to choose multiple options from a predefined list." ---- - -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; -import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; - -# Angular ComboBox Component Overview - -The Angular ComboBox component represents a drop-down list that provides editable functionalities, allowing users to choose multiple options from a predefined list. The Ignite UI for Angular ComboBox Component also provides filtering capabilities, grouping and adding custom values to a dropdown list. It can be used as an alternative to the HTML select tag and has several out-of-the-box features such as data binding (local and remote), filtering, grouping, custom templates for items, header, and footer, custom values, and more. - -## Angular ComboBox Example - -In this Angular ComboBox example, you can see how users can filter items and perform selection with the provided data. In addition, the ComboBox exposes keyboard navigation and custom styling capabilities. - - - -
- -## Angular ComboBox Features - -The combobox control exposes the following features: - -- Data Binding - local data and [remote data](/combo-remote) -- [Value Binding](/combo-features#data-binding) -- [Filtering](/combo-features#filtering) -- [Grouping](/combo-features#grouping) -- [Custom Values](/combo-features#custom-values) -- [Templates](/combo-templates) -- Integration with [Template Driven Forms](/input-group) and [Reactive Forms](/angular-reactive-form-validation) - -## Getting Started with Ignite UI for Angular ComboBox - -To get started with the Ignite UI for Angular ComboBox component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - -```cmd -ng add igniteui-angular -``` - -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. - -The next step is to import the `IgxComboModule` in your **app.module.ts** file. - -```typescript -import { IgxComboModule } from 'igniteui-angular/combo'; -// import { IgxComboModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - imports: [ - ... - IgxComboModule, - ... - ] -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxComboComponent` as a standalone dependency, or use the [`IGX_COMBO_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/combo/src/combo/public_api.ts) token to import the component and all of its supporting components and directives. - -```typescript -// home.component.ts - -import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular/combo'; -// import { IGX_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: '', - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IGX_COMBO_DIRECTIVES] - /* or imports: [IgxComboComponent] */ -}) -export class HomeComponent {} -``` - -Now that you have the Ignite UI for Angular Combo module or directives imported, you can start using the `igx-combo` component. - -## Using the Angular ComboBox Component - -After the initial setup, you can bind the to data. - -```typescript -@Component({ - selector: 'app-combo-demo', - template: '', - styleUrls: ['combo-demo.component.scss'], - standalone: true, - imports: [IGX_COMBO_DIRECTIVES] -}) -export class ComboDemo implements OnInit { - public cities: { name: string, id: string }[] = []; - - public ngOnInit() { - this.cities = [{ name: 'London', id: 'UK01' }, { name: 'Sofia', id: 'BG01'}, ...]; - } -} -``` - -Our combobox is now bound to the array of cities, but we still haven't told the component which property to use for the items' text and which to use for the value. Let's do that now. - -### Data value and display properties - -Since the combobox is bound to an array of complex data (i.e. objects), we need to specify a property that the control will use to handle the selected items. The control exposes two `@Input` properties - and : - -- `valueKey` - _Optional, recommended for object arrays_ - Specifies which property of the data entries will be stored for the combobox's selection. If `valueKey` is omitted, the combobox value will use references to the data entries (i.e. the selection will be an array of entries from `igxCombo.data`). -- `displayKey` - _Required for object arrays_ - Specifies which property will be used for the items' text. If no value is specified for `displayKey`, the combobox will use the specified `valueKey` (if any). - -In our case, we want the combobox to display the `name` of each city and the combobox value to store the `id` of each city. Therefore, we are providing these properties to the combobox's `displayKey` and `valueKey`, respectively: - -```html - -``` - - -When the data source is an array of primitives (e.g. `string[]`, `number[]`), **do not** specify a `valueKey` and `displayKey`. Primitive values will be used for both value and text. - - -### Two-Way Binding - -The combobox component fully supports two-way data-binding with `[(ngModel)]` as well as usage in [template driven](https://angular.io/guide/forms) and [reactive](https://angular.io/guide/reactive-forms) forms. The combobox selection can be accessed either through two-way binding or through the [selection API](#selection-api). We can pass an array of items of the same type as the ones in the combobox's selection (based on `valueKey`) and any time one changes, the other is updated accordingly. - -In the following example, the cities Sofia and London will initially be selected. Any further changes in the combobox's selection will reflect on the `selectedCities` array. - -```html - -``` - -```typescript -export class MyCombo { - public cities: { name: string, id: string }[] = [ - { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...]; - public selectedCities: string[] = ['BG01', 'UK01']; -} -``` - - - -Two-way binding can also be achieved without a specified `valueKey`. For example, if `valueKey` is omitted, the bound model will look like this: - -```typescript -export class MyCombo { - public cities: { name: string, id: string } [] = [ - { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...]; - public selectedCities: { name: string, id: string } [] = [this.cities[0], this.cities[1]]; -} -``` - - - -### Selection API - -The combobox component exposes API that allows getting and manipulating the current selection state of the control. - -One way to get the combobox's selection is via the property. It returns an array of values which correspond to the selected items, depending on the specified [valueKey](#data-value-and-display-properties) (if any). - -In our example, `selection` will return an array of the selected cities' `id`s: - -```typescript -export class MyCombo { - ... - public selection: string[] = this.combo.selection; -} -``` - -Using the selection API, you can also change the combobox's selected items without user interaction with the control - via a button click, as a response to an Observable changing, etc. For example, we can implement a button that selects a set of cities, using the method: - -```html - - -``` - -When clicking the button, the cities London and Sofia will be added to the combobox's selection: - -```typescript -export class MyExampleCombo { - @ViewChild(IgxComboComponent, { read: IgxComboComponent, static: true }) - public combo: IgxComboComponent; - ... - selectFavorites(): void { - this.combo.select(['UK01', 'BG01']); - } -} -``` - -The combobox also fires an event every time its selection changes - . The emitted event arguments, , contain information about the selection prior to the change, the current selection and the items that were added or removed. The event can also be cancelled, preventing the selection update with the new array of items. - -Binding to the event can be done through the proper `@Output` property on the `igx-combo` tag: - -```html - - -``` - -In the following example, when a city is added or removed from the selection, a handler that updates the statistic visualization is fired: - -```typescript -export class MyExampleCombo { - ... - handleCityChange(event: IComboSelectionChangingEventArgs): void { - for (const item of event.added) { - this.addToVisualization(item); - } - for (const item of event.removed) { - this.removeFromVisualization(item); - } - } -} -``` - -Additionally, the combobox fires a event after the selection is committed and the component state has been updated. The emitted event arguments, , contain information about the previous selection, the current selection and the items that were added or removed. Unlike `selectionChanging`, this event is not cancellable and is guaranteed to reflect the final committed selection state. When the combobox is used with `ngModel` or Angular forms, `selectionChanged` is emitted after the value change callback is invoked. - -Binding to the event can be done through the proper `@Output` property on the `igx-combo` tag: - -```html - - -``` - -In the following example, when the selection changes, the handler updates a short summary and tracks how many items were added and removed: - -```typescript -export class MyExampleCombo { - ... - handleCitySelectionChanged(event: IComboSelectionChangedEventArgs): void { - this.updateSelectionSummary(event.displayText, event.newSelection.length); - - for (const item of event.added) { - this.highlightAddedCity(item); - } - - for (const item of event.removed) { - this.dimRemovedCity(item); - } - - this.logSelectionTransition(event.oldSelection, event.newSelection); - } -} -``` - -## Single Selection - -By default, the combo control provides multiple selection. The snippet below demonstrates how to achieve single selection in the component by attaching a handler to the `selectionChanging` event: - -```html - -``` - -```typescript -public singleSelection(event: IComboSelectionChangingEventArgs) { - if (event.added.length) { - event.newValue = event.added; - } -} -``` - -> Note: It is recommended to use the [igxSimpleCombo](/simple-combo) instead of modifying the igxCombo like it is shown above. - -
- -## Keyboard Navigation - -When combobox is closed and focused: - -- `ArrowDown` or `Alt` + `ArrowDown` will open the combobox's drop down and will move focus to the search input. - -- `Esc` will clear the selected value(s) while keeping focus on the combobox. - -- `Tab` will move the focus to the next focusable element outside the combobox. - -When combobox is opened: - -- `Esc` will close the list and keep the focus on the combobox. - -- `Tab` will close the list and move focus to the next focusable element. - -When combobox is opened and search input is focused: - -- `ArrowUp` or `Alt` + `ArrowUp` will close the combobox's drop down and will move focus to the closed combobox. - -- `ArrowDown` will move focus from the search input to the first list item. If the list is empty and custom values are enabled will move it to the Add new item button. - - -Any other key stroke will be handled by the input. - - -When combobox is opened and list item is focused: - -- `ArrowDown` will move to the next list item. If the active item is the last one in the list and custom values are enabled, the focus will be moved to the Add item button. - -- `ArrowUp` will move to the previous list item. If the active item is the first one in the list, the focus will be moved back to the search input. - -- `End` will move to the last list item. - -- `Home` will move to the first list item. - -- `Space` will select/deselect the active list item. - -- `Enter` will confirm the already selected items and will close the list. - -When combobox is opened, allow custom values are enabled and add item button is focused: - -- `Enter` will add a new item with `valueKey` and `displayKey` equal to the text in the search input and will select the new item. - -- `ArrowUp` focus will be moved back to the last list item or if the list is empty, will be moved to the search input. - -## Styling - -### Combo Theme Property Map - -When you modify a primary property, all related dependent properties are updated automatically: - -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$empty-list-background** | $empty-list-placeholder-color | The combo placeholder text color. | -| **$toggle-button-background** | $toggle-button-foreground | The combo toggle button foreground color. | -| | $toggle-button-background-focus | The combo toggle button background color when focused. | -| | $toggle-button-background-focus--border | The combo toggle button background color when focused (border variant). | -| | $toggle-button-foreground-filled | The combo toggle button foreground color when filled. | -| | $toggle-button-background-disabled | The combo toggle button background color when disabled. | -| | $toggle-button-foreground-disabled | The combo toggle button foreground color when disabled. | -| **$toggle-button-background-focus** | $toggle-button-foreground-focus | The combo toggle button foreground color when focused. | -| **$clear-button-background-focus** | $clear-button-foreground-focus | The combo clear button foreground color when focused. | - -Using the [`Ignite UI for Angular Theming`](/themes), we can greatly alter the combobox appearance. First, in order for us to use the functions exposed by the theme engine, we need to import the `index` file in our style file: - -```scss -@use "igniteui-angular/theming" as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; -``` - -Following the simplest approach, we create a new theme that extends the . By setting the `$toggle-button-background`, the theme automatically determines suitable state colors and contrast foregrounds for the button. You can also specify additional parameters, such as `$search-separator-border-color`: - -```scss -$custom-combo-theme: combo-theme( - $search-separator-border-color: #1d3743, - $toggle-button-background: #57a5cd, -); -``` - -The uses the internally as an item container. It also includes the and the components. Creating new themes, that extend these components' themes, and scoping them under the respective classes will let you change the combobox styles: - -```scss -$custom-drop-down-theme: drop-down-theme( - $background-color: #57a5cd, -); - -$custom-checkbox-theme: checkbox-theme( - $border-radius: 10px, - $fill-color: #1d3743, - $empty-color: #1d3743, -); -``` - -The last step is to include the component's theme. - -```scss -:host { - @include tokens($custom-combo-theme); - @include tokens($custom-drop-down-theme); - @include tokens($custom-checkbox-theme); -} -``` - - -The uses the [`IgxOverlay`](/overlay) service to display its list. Depending on View Encapsulation and where the generated selectors must match, the local theme include may still require `::ng-deep`. A list attached to the default detached outlet also cannot inherit from the combo's host; configure the beneath the themed container or emit the theme from a selector that can match the outlet. See the [`IgxOverlay Styling Guide`](/overlay-styling). -[!Note] -The default `type` of the `IgxCombo` is `box` unlike the [`IgxSelect`](/select) where it is `line`. - - -### Demo - - - -
- -### Styling with Tailwind - -You can style the `combo` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. - -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: - -```scss -@import "tailwindcss"; -... -@use 'igniteui-theming/tailwind/utilities/material.css'; -``` - -The utility file includes both `light` and `dark` theme variants. - -- Use `light-*` classes for the light theme. -- Use `dark-*` classes for the dark theme. -- Append the component name after the prefix, e.g., `light-combo`, `dark-combo`. - -Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using `arbitrary properties`. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.). - -You can find the full list of properties in the . The syntax is as follows: - -```html - -``` - - -The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme. - - -At the end your combo should look like this: - - - -## Known Issues - -- The combobox input that displays the selected items is not editable. However, due to browser specifics in FireFox, the cursor is visible. -- When the combobox is bound to an array of primitive data which contains `undefined` (i.e. `[ undefined, ...]`), `undefined` is not displayed in the dropdown. When it is bound to an array of complex data (i.e. objects) and the value used for `valueKey` is `undefined`, the item will be displayed in the dropdown, but cannot be selected. -- When the combobox is bound to a remote service and there is a predefined selection, its input will remain blank until the requested data is loaded. - - -The combobox uses the [Virtual Scroll](./layouts/virtual-scroll.mdx) component internally to virtualize its list, hence all Virtual Scroll limitations are valid for the combobox. For more details see the [Virtual Scroll Known Limitations](./layouts/virtual-scroll.mdx#known-limitations) section. - - -## API References -
-- -- -Additional [angular components](https://www.infragistics.com/products/ignite-ui-angular) and/or directives with relative APIs that were used: -- -- -- -## Theming Dependencies - -- -- -- -- - -## Additional Resources - -
- -- [ComboBox Features](/combo-features) -- [ComboBox Remote Binding](/combo-remote) -- [ComboBox Templates](/combo-templates) -- [Template Driven Forms Integration](/input-group) -- [Reactive Forms Integration](/angular-reactive-form-validation) -- [Single Select ComboBox](/simple-combo) - -Our community is active and always welcoming to new ideas. - -- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/expansion-panel.mdx b/docs/angular/src/content/en/components/expansion-panel.mdx index 4d49687e13..7f24299da8 100644 --- a/docs/angular/src/content/en/components/expansion-panel.mdx +++ b/docs/angular/src/content/en/components/expansion-panel.mdx @@ -194,7 +194,7 @@ We can do that by passing content in an `igx-expansion-panel-icon` tag: Our Angular Expansion Panel will now render "Show More" when the panel is collapsed and "Show Less" once it's fully expanded. -The `IgxExpansionPanel` control allows all sorts of content to be added inside of the `igx-expansion-panel-body`. It can render [`IgxGrid`](/grid/grid)s, [`IgxCombo`](/combo), charts and even other expansion panels! +The `IgxExpansionPanel` control allows all sorts of content to be added inside of the `igx-expansion-panel-body`. It can render [`IgxGrid`](/grid/grid)s, [`IgxCombo`](/inputs/combo/overview), charts and even other expansion panels! For the sake of simplicity let's add some basic markup to the body of our expansion panel. diff --git a/docs/angular/src/content/en/components/general/cli/component-templates.mdx b/docs/angular/src/content/en/components/general/cli/component-templates.mdx index d073cce00c..8d49904cf4 100644 --- a/docs/angular/src/content/en/components/general/cli/component-templates.mdx +++ b/docs/angular/src/content/en/components/general/cli/component-templates.mdx @@ -59,8 +59,8 @@ These templates generate components into an existing Angular workspace only. The | snackbar | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c snackbar newSnackbar
Ignite UI CLI:
ig add snackbar newSnackbar
Basic IgxSnackbar sample.
| [IgxSnackbar](../../snackbar.mdx) showing a brief message with an optional action. | | toast | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c toast newToast
Ignite UI CLI:
ig add toast newToast
Basic IgxToast sample.
| [IgxToast](../../toast.mdx) showing a non-interactive notification. | | Data Entry & Display | | | -| combo | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c combo newCombo
Ignite UI CLI:
ig add combo newCombo
Basic IgxCombo with templating.
| [IgxCombo](../../combo.mdx) with custom [templating](../../combo-templates.mdx). | -| simple-combo | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c simple-combo newSimpleCombo
Ignite UI CLI:
ig add simple-combo newSimpleCombo
Basic IgxSimpleCombo sample.
| [IgxSimpleCombo](../../simple-combo.mdx) with single selection. | +| combo | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c combo newCombo
Ignite UI CLI:
ig add combo newCombo
Basic IgxCombo with templating.
| [IgxCombo](../../inputs/combo/overview.mdx) with custom [templating](../../inputs/combo/templates.mdx). | +| simple-combo | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c simple-combo newSimpleCombo
Ignite UI CLI:
ig add simple-combo newSimpleCombo
Basic IgxSimpleCombo sample.
| [IgxSimpleCombo](../../inputs/combo/single-selection.mdx) with single selection. | | badge | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c badge newBadge
Ignite UI CLI:
ig add badge newBadge
Basic IgxBadge sample.
| [IgxBadge](../../inputs/badge.mdx) displaying a status indicator. | | button-group | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c button-group newButtonGroup
Ignite UI CLI:
ig add button-group newButtonGroup
Basic IgxButtonGroup sample.
| [IgxButtonGroup](../../inputs/button-group.mdx) with a set of toggle buttons. | | checkbox | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c checkbox newCheckbox
Ignite UI CLI:
ig add checkbox newCheckbox
Basic IgxCheckbox sample.
| [IgxCheckbox](../../inputs/checkbox.mdx) for binary choices. | diff --git a/docs/angular/src/content/en/components/general/update-guide.mdx b/docs/angular/src/content/en/components/general/update-guide.mdx index ccaa6d9315..26840a30a5 100644 --- a/docs/angular/src/content/en/components/general/update-guide.mdx +++ b/docs/angular/src/content/en/components/general/update-guide.mdx @@ -1525,7 +1525,7 @@ The `ng update` process will update all enumeration names, like `AvatarType`, `T ``` - IgxCombo - - The way that the [`igx-combo`](/combo) handles selection and data binding is changed. + - The way that the [`igx-combo`](/inputs/combo/overview) handles selection and data binding is changed. - If the combo's [`valueKey`] input is defined, the control will look for that specific property in the passed array of data items when performing selection. **All** selection events are handled with the value of the data items' `valueKey` property. @@ -1564,7 +1564,7 @@ The `ng update` process will update all enumeration names, like `AvatarType`, `T } ``` - You can read more about setting up the combo in the [readme](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/src/lib/combo/README.md#value-binding) and in the [official documentation](/combo#selection-api). + You can read more about setting up the combo in the [readme](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/src/lib/combo/README.md#value-binding) and in the [official documentation](/inputs/combo/overview#value-and-selection). ## From 8.0.x to 8.1.x diff --git a/docs/angular/src/content/en/components/grids-and-lists.mdx b/docs/angular/src/content/en/components/grids-and-lists.mdx index 7618ee456a..22ff06eaf5 100644 --- a/docs/angular/src/content/en/components/grids-and-lists.mdx +++ b/docs/angular/src/content/en/components/grids-and-lists.mdx @@ -149,7 +149,7 @@ Full support for exporting data grids to XLSX, XLS, TSV or CSV. The Ignite UI fo - [Grid-level Searching](/grid/search) - [Export to Excel, CSV, TSV](/exporter-excel) - [Multi-Column Headers](/grid/multi-column-headers) -- [Combo Box/Dropdown](/combo) +- [Combo Box/Dropdown](/inputs/combo/overview) - [Virtualization and Performance](/grid/virtualization) - [Remote Data Load on Demand](/grid/virtualization#remote-virtualization) - [Cell Templates](/grid/grid#cell-template) diff --git a/docs/angular/src/content/en/components/overlay-styling.mdx b/docs/angular/src/content/en/components/overlay-styling.mdx index a418b0766a..092ca739d9 100644 --- a/docs/angular/src/content/en/components/overlay-styling.mdx +++ b/docs/angular/src/content/en/components/overlay-styling.mdx @@ -18,7 +18,7 @@ import Sample from 'igniteui-astro-components/components/mdx/Sample.astro';
-[`IgxOverlayService`](/overlay) is used to display content above the page content. A lot of Ignite UI for Angular components use the overlay - [Drop Down](/drop-down), [Combo](/combo), [Date Picker](/date-picker) and more - so it is important to understand how the overlay displays content. +[`IgxOverlayService`](/overlay) is used to display content above the page content. A lot of Ignite UI for Angular components use the overlay - [Drop Down](/drop-down), [Combo](/inputs/combo/overview), [Date Picker](/date-picker) and more - so it is important to understand how the overlay displays content. To display the content above other elements, the service moves it into a special outlet container (attached at the end of the document's body, by default). This behavior can affect styles [scoped to specific container](#scoped-overlay-styles).
@@ -53,7 +53,7 @@ Because these universal overrides are global, the drop-down content can consume A local theme can only affect overlay content that inherits from its container or matches its generated selectors. Content attached to the default outlet at the end of `body` is not a descendant of the component that opened it. -For example, the `igx-combo` item [styles](/combo#styling) use the drop-down theme. This component-local theme takes effect after the combo outlet is moved beneath the host: +For example, the `igx-combo` item [styles](/inputs/combo/overview#styling) use the drop-down theme. This component-local theme takes effect after the combo outlet is moved beneath the host: ```scss // overlay-styling.component.scss diff --git a/docs/angular/src/content/en/components/simple-combo.mdx b/docs/angular/src/content/en/components/simple-combo.mdx deleted file mode 100644 index 2611067d5d..0000000000 --- a/docs/angular/src/content/en/components/simple-combo.mdx +++ /dev/null @@ -1,422 +0,0 @@ ---- -title: Single Select ComboBox Component - MIT license -description: The Ignite UI for Angular Simple ComboBox provides a powerful input, combining features of the basic HTML input, select, filtering and custom drop-down lists. Try it for FREE -keywords: angular single selection combobox, angular combobox component, angular single selection combobox component, angular combo, angular ui components, ignite ui for angular, infragistics -license: MIT -llms: - description: "The Angular Single Select ComboBox component is a modification of ComboBox component that allows single selection." ---- - -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; -import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; - -# Angular Single Select ComboBox Component Overview - -The Angular Single Select ComboBox component is a modification of [ComboBox component](/combo) that allows single selection. We call it "simple combo". Due to high demand for single-selection mode for the original ComboBox component, we created an extension component which offers an editable search input that allows users to choose an option from a predefined list of items and to input custom values. - -## Angular Simple ComboBox Example - -In this Angular Simple ComboBox example, you can see how users can select the chart's trend line type. In addition, the Simple ComboBox exposes keyboard navigation and custom styling capabilities. - -
- - - -
- -## Angular Simple ComboBox Features - -The simple combobox control exposes the following features: - - Data Binding - local data and remote data - - Value Binding - - Filtering - - Grouping - - Custom Values - - Templates - - Integration with Template Driven Forms and Reactive Forms - -## Getting Started with Ignite UI for Angular Simple ComboBox - -To get started with the Ignite UI for Angular Simple ComboBox component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - -```cmd -ng add igniteui-angular -``` - -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. - -The next step is to import the `IgxSimpleComboModule` in your **app.module.ts** file. - -```typescript -import { IgxSimpleComboModule } from 'igniteui-angular/simple-combo'; -// import { IgxSimpleComboModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - imports: [ - ... - IgxSimpleComboModule, - ... - ] -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxSimpleComboComponent` as a standalone dependency, or use the [`IGX_SIMPLE_COMBO_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/simple-combo/src/simple-combo/public_api.ts) token to import the component and all of its supporting components and directives. - -```typescript -// home.component.ts - -import { IGX_SIMPLE_COMBO_DIRECTIVES } from 'igniteui-angular/simple-combo'; -// import { IGX_SIMPLE_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: '', - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IGX_SIMPLE_COMBO_DIRECTIVES] - /* or imports: [IgxSimpleComboComponent] */ -}) -export class HomeComponent {} -``` - -Now that you have the Ignite UI for Angular Simple ComboBox module or directives imported, you can start using the `igx-simple-combo` component. - -## Using the Angular Simple ComboBox - -Just like the regular combobox, you can bind the to data. - -```typescript -export class MySimpleComboComponent implements OnInit { - public cities: City[]; - - public ngOnInit() { - this.cities = getCitiesByPopulation(10000000); - } -} -``` - -```html - -``` - -Our simple combobox is now bound to the array of cities. - -### Data value and display properties - -Since the simple combobox is bound to an array of complex data (i.e. objects), we need to specify a property that the control will use to handle the selected items. The control exposes two `@Input` properties - and : - -- `valueKey` - _Optional, recommended for object arrays_ - Specifies which property of the data entries will be stored for the simple combobox's selection. If `valueKey` is omitted, the simple combobox value will use references to the data entries (i.e. the selection will be an array of entries from `igxSimpleCombo.data`). -- `displayKey` - _Required for object arrays_ - Specifies which property will be used for the items' text. If no value is specified for `displayKey`, the simple combobox will use the specified `valueKey` (if any). - -In our case, we want the simple combobox to display the `name` of each city and its value to store the `id` of each city. Therefore, we are binding these properties as values to the simple combobox's `displayKey` and `valueKey`, respectively: - -```html - -``` - - -When the data source is comprised of a simple type (e.g. `string[]`, `number[]`), **do not** specify a `valueKey` and `displayKey`. - - -### Two-Way Binding - -The simple combobox component fully supports two-way data-binding with `[(ngModel)]` as well as usage in [template driven](https://angular.io/guide/forms) and [reactive](https://angular.io/guide/reactive-forms) forms. The simple combobox selection can be accessed either through two-way binding or through the [selection API](#selection-api). We can pass in an item of the same type as the ones in the simple combobox's selection (based on `valueKey`) and any time one changes, the other is updated accordingly. - -In the following example, the first city in the provided data will initially be selected. Any further changes in the simple combobox's selection will reflect on the `selectedCities`. - -```html - -``` - -```typescript -export class MySimpleComboComponent implements OnInit { - public cities: City[]; - public selectedCity: number; - - public ngOnInit(): void { - this.cities = getCitiesByPopulation(10000000); - this.selectedCity = this.cities[0].id; - } -} -``` - - - -Two-way binding can also be achieved without a specified `valueKey`. For example, if `valueKey` is omitted, the bound model will look like this: - -```typescript -export class MySimpleComboComponent { - public cities: City[] = [ - { name: 'Sofia', id: '1' }, { name: 'London', id: '2' }, ...]; - public selectedCity: City = this.cities[0]; -} -``` - -### Selection API - -The simple combobox component exposes API that allows getting and manipulating the current selection state of the control. - -One way to get its selection is via the property. It returns a value which corresponds to the selected item, depending on the specified [valueKey](#data-value-and-display-properties) (if any). - -In our example, `selection` will return the selected city's `id`: - -```typescript -export class MySimpleComboComponent { - ... - public selection: string = this.simpleCombo.selection; -} -``` - -Using the selection API, you can also change the simple combobox's selected item without user interaction with the control - via a button click, as a response to an Observable changing, etc. For example, we can implement a button that selects a city, using the method: - -```html - - -``` - -When the button is clicked, `London` will be added to the simple combobox's selection: - -```typescript -export class MySimpleComboComponent { - @ViewChild(IgxSimpleComboComponent, { read: IgxSimpleComboComponent, static: true }) - public simpleCombo: IgxSimpleComboComponent; - ... - selectFavorites(): void { - this.simpleCombo.select('2'); - } -} -``` - -The simple combobox also fires an event every time its selection changes - . The emitted event arguments, , contain information about the selection prior to the change, the current selection and the displayed item. The event can also be cancelled, preventing the selection from taking place. - -Binding to the event can be done through the proper `@Output` property on the `igx-simple-combo` tag: - -```html - - -``` - -
- -## Keyboard Navigation - -When the simple combobox is closed and focused: - -- `ArrowDown` or `Alt` + `ArrowDown` will open the simple combobox's dropdown. - -- `Esc` will clear the selected value while keeping focus on the combobox. - -- `Tab` will move the focus to the next focusable element outside the combobox. - - -Any other key stroke will be handled by the input. - - -When the simple combobox is opened and an item in the list is focused: - -- `ArrowDown` will move to the next list item. If the active item is the last one in the list and custom values are enabled, the focus will be moved to the Add item button. - -- `ArrowUp` will move to the previous list item. If the active item is the first one in the list, the focus will be moved back to the search input while also selecting all of the text in the input. - -- `End` will move to the last list item. - -- `Home` will move to the first list item. - -- `Space` will select/deselect the active list item. - -- `Enter` will select/deselect the active list item and will close the list. - -- `Esc` will close the list and keep the focus on the combobox. - -- `Tab` will close the list and move focus to the next focusable element. - -When the simple combobox is opened and allow custom values are enabled, and add item button is focused: - -- `Enter` will add a new item with `valueKey` and `displayKey` equal to the text in the search input and will select the new item. - -- `ArrowUp` will move the focus back to the last list item or if the list is empty, will move the focus to the input. - -## Cascading Scenario - -The following sample demonstrates a scenario where the is used: - - - -Check out our [Angular Grid with Cascading Combos Sample](/grid/cascading-combos). - -
- -### Template Configuration - -The API of the simple combobox is used to get the selected item from one component and load the data source for the next one, as well as clear the selection and data source when needed. - -```html - - - - - - -``` - -### Component Definition - -```typescript -export class SimpleComboCascadingComponent implements OnInit { - public selectedCountry: Country; - public selectedRegion: Region; - public selectedCity: City; - public countriesData: Country[]; - public regionData: Region[] = []; - public citiesData: City[] = []; - public ngOnInit(): void { - this.countriesData = getCountries(['United States', 'Japan', 'United Kingdom']); - } - - public countryChanging(e: ISimpleComboSelectionChangingEventArgs) { - this.selectedCountry = e.newSelection as Country; - this.regionData = getCitiesByCountry([this.selectedCountry?.name]) - .map(c => ({name: c.region, country: c.country})) - .filter((v, i, a) => a.findIndex(r => r.name === v.name) === i); - this.selectedRegion = null; - this.selectedCity = null; - this.citiesData = []; - } - - public regionChanging(e: ISimpleComboSelectionChangingEventArgs) { - this.selectedRegion = e.newSelection as Region; - this.citiesData = getCitiesByCountry([this.selectedCountry?.name]) - .filter(c => c.region === this.selectedRegion?.name); - this.selectedCity = null; - } -} -``` - -## Angular Simple ComboBox Remote Binding - -The Ignite UI for Angular Simple ComboBox Component exposes an API that allows binding a combobox to a remote service and retrieving data on demand. - -### Demo - -The sample below demonstrates remote binding using the property to load new chunk of remote data and following the steps described in [ComboBox Remote Binding](/combo-remote): - - - -## Styling - -Using the [`Ignite UI for Angular Theming`](/themes), we can greatly alter the simple combobox appearance. First, in order for us to use the functions exposed by the theme engine, we need to import the `index` file in our style file: - -```scss -@use 'igniteui-angular/theming' as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; -``` - -Following the simplest approach, we create a new theme that extends the and accepts the `$empty-list-background` parameter: - -```scss -$custom-simple-combo-theme: combo-theme( - $empty-list-background: #1a5214 -); -``` - -The uses the internally as an item container. It also includes the component. Creating new themes, that extend these components' themes, and scoping them under the respective classes will let's you change the simple combobox styles: - -```scss -$custom-drop-down-theme: drop-down-theme( - $background-color: #d9f5d6, - $header-text-color: #1a5214, - $item-text-color: #1a5214, - - $focused-item-background: #72da67, - $focused-item-text-color: #1a5214, - $hover-item-background: #a0e698, - $hover-item-text-color: #1a5214, - - $selected-item-background: #a0e698, - $selected-item-text-color: #1a5214, - $selected-hover-item-background: #72da67, - $selected-hover-item-text-color: #1a5214, - $selected-focus-item-background: #72da67, - $selected-focus-item-text-color: #1a5214, -); -``` - -The last step is to include the component's theme. - -```scss -:host { - @include tokens($custom-combo-theme); - @include tokens($custom-drop-down-theme); -} -``` - - -The uses the [`IgxOverlay`](/overlay) service to display its list. Depending on View Encapsulation and where the generated selectors must match, the local theme include may still require `::ng-deep`. A list attached to the default detached outlet also cannot inherit from the combo's host; configure the beneath the themed container or emit the theme from a selector that can match the outlet. See the [`IgxOverlay Styling Guide`](/overlay-styling). -[!Note] -The default `type` of the `IgxSimpleCombo` is `box` unlike the [`IgxSelect`](/select) where it is `line`. - - -### Demo - - - -
- -## Known Issues - -- When the simple combobox is bound to an array of primitive data which contains `undefined` (i.e. `[ undefined, ...]`), `undefined` is not displayed in the dropdown. When it is bound to an array of complex data (i.e. objects) and the value used for `valueKey` is `undefined`, the item will be displayed in the dropdown, but cannot be selected. -- When the simple combobox is bound via `ngModel` and is marked as `required`, `null`, `undefined` and `''` values cannot be selected. -- When the simple combobox is bound to a remote service and there is a predefined selection, its input will remain blank until the requested data is loaded. - - -The simple combobox uses the [Virtual Scroll](./layouts/virtual-scroll.mdx) component internally to virtualize its list, hence all Virtual Scroll limitations are valid for the simple combobox. For more details see the [Virtual Scroll Known Limitations](./layouts/virtual-scroll.mdx#known-limitations) section. - - -## API References -
-- -- -Additional components and/or directives with relative APIs that were used: -- -- -## Theming Dependencies - -- -- -- - -## Additional Resources - -
- -- [ComboBox Features](/combo-features) -- [ComboBox Remote Binding](/combo-remote) -- [ComboBox Templates](/combo-templates) -- [Template Driven Forms Integration](/input-group) -- [Reactive Forms Integration](/angular-reactive-form-validation) - -Our community is active and always welcoming to new ideas. - -- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/themes/roundness.mdx b/docs/angular/src/content/en/components/themes/roundness.mdx index 016c5dabbb..253da85658 100644 --- a/docs/angular/src/content/en/components/themes/roundness.mdx +++ b/docs/angular/src/content/en/components/themes/roundness.mdx @@ -20,7 +20,7 @@ Many Ignite UI components have predefined minimum and maximum border-radius valu When you set `--ig-radius-factor` to 0, the component uses its minimum border-radius and will appear more block-like with sharp corners. When set to 1, the component uses its maximum predefined border-radius and will appear rounded. Here is a list of the components that have predefined minimum and maximum border-radius values and can be modified using the `--ig-radius-factor` variable:
-• [Action Strip](/action-strip) • [Button](inputs/button) • [Button Group](/inputs/button-group) • [Calendar](/calendar) • [Card](/layouts/card) • [Carousel](/layouts/carousel) • [Checkbox](/inputs/checkbox) • [Chip](/inputs/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/inputs/radio) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](inputs/switch) • [Toast](/toast) +• [Action Strip](/action-strip) • [Button](inputs/button) • [Button Group](/inputs/button-group) • [Calendar](/calendar) • [Card](/layouts/card) • [Carousel](/layouts/carousel) • [Checkbox](/inputs/checkbox) • [Chip](/inputs/chip) • [Combo](/inputs/combo/overview) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/inputs/radio) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](inputs/switch) • [Toast](/toast) ## Usage diff --git a/docs/angular/src/content/en/components/toc.json b/docs/angular/src/content/en/components/toc.json index eedcfb11a2..cd53c2b5f0 100644 --- a/docs/angular/src/content/en/components/toc.json +++ b/docs/angular/src/content/en/components/toc.json @@ -1316,8 +1316,8 @@ }, { "name": "Combo", - "href": "combo.mdx", - "new": false, + "href": "inputs/combo/overview.mdx", + "updated": true, "items": [ { "name": "Features", @@ -1331,13 +1331,13 @@ }, { "name": "Templates", - "href": "combo-templates.mdx", - "new": false + "href": "inputs/combo/templates.mdx", + "updated": true }, { - "name": "Single Select ComboBox", - "href": "simple-combo.mdx", - "new": false + "name": "Single Selection", + "href": "inputs/combo/single-selection.mdx", + "updated": true } ] }, diff --git a/docs/angular/src/content/en/grids_templates/cascading-combos.mdx b/docs/angular/src/content/en/grids_templates/cascading-combos.mdx index 993e9335c0..fe3b8c3167 100644 --- a/docs/angular/src/content/en/grids_templates/cascading-combos.mdx +++ b/docs/angular/src/content/en/grids_templates/cascading-combos.mdx @@ -11,7 +11,7 @@ import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; # Angular Grid with Cascading Combos -The Grid's Editing functionality provides with the opportunity to use [Cascading Combos](/simple-combo#cascading-scenario). By selecting the value in any preceding [Combos](/combo), the users will receive only the data that is relevant to their selection within the next Combo. +The Grid's Editing functionality provides with the opportunity to use [Cascading Combos](/inputs/combo/single-selection#value-and-selection). By selecting the value in any preceding [Combos](/inputs/combo/overview), the users will receive only the data that is relevant to their selection within the next Combo. ## Angular Grid with Cascading Combos Sample Overview @@ -26,9 +26,9 @@ The sample below demonstrates how `Grid` works with nested `Cascading Combos`. In order enable column editing, make sure property is set to **true**. -Once the column editing is enabled, you can start by adding your [Single Select ComboBox](/simple-combo). Please note that here in order to have only one single selection available, you will need to use [igxSimpleCombo](/simple-combo) instead of modifying the igxCombo. +Once the column editing is enabled, you can start by adding your [Single Select ComboBox](/inputs/combo/single-selection). Please note that here in order to have only one single selection available, you will need to use [igxSimpleCombo](/inputs/combo/single-selection) instead of modifying the igxCombo. -To get started with the [Simple ComboBox component](/simple-combo#angular-simple-combobox-features), first you need to import the `IgxSimpleComboModule` in your **app.module.ts** file: +To get started with the [Simple ComboBox component](/inputs/combo/single-selection#getting-started), first you need to import the `IgxSimpleComboModule` in your **app.module.ts** file: ```typescript import { IgxSimpleComboModule } from 'igniteui-angular/simple-combo'; @@ -98,6 +98,6 @@ The is necessary to - [{ComponentTitle} Editing](/{igPath}/editing) -- [Single Select ComboBox](/simple-combo) -- [Cascading Combos](/simple-combo#cascading-scenario) +- [Single Select ComboBox](/inputs/combo/single-selection) +- [Cascading Combos](/inputs/combo/single-selection#value-and-selection) - [Linear Progress](/linear-progress) diff --git a/docs/angular/src/content/en/grids_templates/cell-editing.mdx b/docs/angular/src/content/en/grids_templates/cell-editing.mdx index fb8289c96f..07ff957328 100644 --- a/docs/angular/src/content/en/grids_templates/cell-editing.mdx +++ b/docs/angular/src/content/en/grids_templates/cell-editing.mdx @@ -64,7 +64,7 @@ Ignite UI for Angular {ComponentTitle} component provides powerful data manipula -By using `igxCellEditor` with any type of editor component, the keyboard navigation flow will be disrupted. The same applies to direct editing of the custom cell that enters edit mode. This is because the `focus` will remain on the `cell element`, not on the editor component that we've added - [`igxSelect`](/select), [`igxCombo`](/combo), etc. This is why we should take leverage of the `igxFocus` directive, which will move the focus directly in the in-cell component and will preserve `a fluent editing flow` of the cell/row. +By using `igxCellEditor` with any type of editor component, the keyboard navigation flow will be disrupted. The same applies to direct editing of the custom cell that enters edit mode. This is because the `focus` will remain on the `cell element`, not on the editor component that we've added - [`igxSelect`](/select), [`igxCombo`](/inputs/combo/overview), etc. This is why we should take leverage of the `igxFocus` directive, which will move the focus directly in the in-cell component and will preserve `a fluent editing flow` of the cell/row. ## Cell Editing @@ -199,7 +199,7 @@ The cell editing template directive `igxCellEditor`, handles how a column's cell -By using `igxCellEditor` with any type of editor component, the keyboard navigation flow will be disrupted. The same applies to direct editing of the custom cell that enters edit mode. This is because the `focus` will remain on the `cell element`, not on the editor component that we've added - [`igxSelect`](/select), [`igxCombo`](/combo), etc. This is why we should take leverage of the `igxFocus` directive, which will move the focus directly in the in-cell component and will preserve `a fluent editing flow` of the cell/row. +By using `igxCellEditor` with any type of editor component, the keyboard navigation flow will be disrupted. The same applies to direct editing of the custom cell that enters edit mode. This is because the `focus` will remain on the `cell element`, not on the editor component that we've added - [`igxSelect`](/select), [`igxCombo`](/inputs/combo/overview), etc. This is why we should take leverage of the `igxFocus` directive, which will move the focus directly in the in-cell component and will preserve `a fluent editing flow` of the cell/row. diff --git a/docs/angular/src/content/en/images/anatomy-content-light/combo-input-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/combo-input-lt-a.png new file mode 100644 index 0000000000..b39f02384e Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/combo-input-lt-a.png differ diff --git a/docs/angular/src/content/en/images/anatomy-content-light/single-select-combo-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/single-select-combo-lt-a.png new file mode 100644 index 0000000000..a5654484be Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/single-select-combo-lt-a.png differ diff --git a/docs/angular/src/content/en/images/combo/combo-do-1.png b/docs/angular/src/content/en/images/combo/combo-do-1.png new file mode 100644 index 0000000000..2577ce75ee Binary files /dev/null and b/docs/angular/src/content/en/images/combo/combo-do-1.png differ diff --git a/docs/angular/src/content/en/images/combo/combo-do-not-1.png b/docs/angular/src/content/en/images/combo/combo-do-not-1.png new file mode 100644 index 0000000000..29070f1593 Binary files /dev/null and b/docs/angular/src/content/en/images/combo/combo-do-not-1.png differ diff --git a/docs/angular/src/content/en/images/combo/single-select-combo-do-1.png b/docs/angular/src/content/en/images/combo/single-select-combo-do-1.png new file mode 100644 index 0000000000..4df3ee9b7f Binary files /dev/null and b/docs/angular/src/content/en/images/combo/single-select-combo-do-1.png differ diff --git a/docs/angular/src/content/en/images/combo/single-select-combo-do-not-1.png b/docs/angular/src/content/en/images/combo/single-select-combo-do-not-1.png new file mode 100644 index 0000000000..f23840fdc6 Binary files /dev/null and b/docs/angular/src/content/en/images/combo/single-select-combo-do-not-1.png differ diff --git a/docs/xplat/src/assets/images/anatomy-content-light/single-select-combo-lt-a.png b/docs/xplat/src/assets/images/anatomy-content-light/single-select-combo-lt-a.png new file mode 100644 index 0000000000..a5654484be Binary files /dev/null and b/docs/xplat/src/assets/images/anatomy-content-light/single-select-combo-lt-a.png differ diff --git a/docs/xplat/src/assets/images/combo/combo-do-1.png b/docs/xplat/src/assets/images/combo/combo-do-1.png new file mode 100644 index 0000000000..2577ce75ee Binary files /dev/null and b/docs/xplat/src/assets/images/combo/combo-do-1.png differ diff --git a/docs/xplat/src/assets/images/combo/combo-do-not-1.png b/docs/xplat/src/assets/images/combo/combo-do-not-1.png new file mode 100644 index 0000000000..29070f1593 Binary files /dev/null and b/docs/xplat/src/assets/images/combo/combo-do-not-1.png differ diff --git a/docs/xplat/src/assets/images/combo/single-select-combo-do-1.png b/docs/xplat/src/assets/images/combo/single-select-combo-do-1.png new file mode 100644 index 0000000000..4df3ee9b7f Binary files /dev/null and b/docs/xplat/src/assets/images/combo/single-select-combo-do-1.png differ diff --git a/docs/xplat/src/assets/images/combo/single-select-combo-do-not-1.png b/docs/xplat/src/assets/images/combo/single-select-combo-do-not-1.png new file mode 100644 index 0000000000..f23840fdc6 Binary files /dev/null and b/docs/xplat/src/assets/images/combo/single-select-combo-do-not-1.png differ diff --git a/docs/xplat/src/content/en/components/inputs/combo/overview.mdx b/docs/xplat/src/content/en/components/inputs/combo/overview.mdx index 4451f1b8dd..6337cfaf62 100644 --- a/docs/xplat/src/content/en/components/inputs/combo/overview.mdx +++ b/docs/xplat/src/content/en/components/inputs/combo/overview.mdx @@ -1,61 +1,187 @@ --- -title: "{Platform} ComboBox Component – {ProductName}" -description: "{Platform} Combo component provides a powerful input, combining features of the basic HTML input, select, filtering and custom drop-down lists. Try it for FREE" -keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} ComboBox component" +title: "{Platform} Combo Component" +description: "The {ProductName} Combo combines an input field with a searchable dropdown list, so users can filter the options by typing and select one or more items." +keywords: "{Platform} Combo, {ProductName}, combobox, multi-select dropdown, searchable dropdown, combo filtering, combo grouping" license: MIT +last_updated: "2026-11-03" +relatedComponents: ["Select", "Dropdown"] mentionedTypes: ["Combo", "ComboItem", "ComboHeader", "ComboList"] llms: - description: "{Platform} ComboBox is a lightweight editor that enables users to easily select, filter, and group different predefined options in a provided list." + description: "The {ProductName} 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." --- -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import DoDont from 'igniteui-astro-components/components/mdx/DoDont.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import comboAnatomy from '@xplat-images/anatomy-content-light/combo-input-lt-a.png'; +import comboDoAlignment from '@xplat-images/combo/combo-do-1.png'; +import comboDoNotAlignment from '@xplat-images/combo/combo-do-not-1.png'; +# Combo -# {Platform} ComboBox Overview +The {ProductName} 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. -{Platform} 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 {Platform} ComboBox keyboard navigation, templates to customize how the items, header, and footer are displayed. + -The {ProductName} 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. +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. -## {Platform} ComboBox Example + + + - +The Combo shows its options in a virtualized list, so the list can hold thousands of options. The Combo supports case-sensitive filtering, grouping, and binding to complex data. + -## Getting Started with {Platform} ComboBox +## 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. + + + + + +1. Input Container: displays the value and input elements
+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 `igc-combo` element renders its input field and its dropdown list in a popover, and the helper text below them: + +```text +igc-combo +└─ #shadow-root + ├─ igc-popover + │ ├─ igc-input#target[slot="anchor"] // the input field, exported as the "input" part + │ │ ├─ slot[name="prefix"] + │ │ ├─ span[part="clear-icon"] // shown when the Combo has a value + │ │ ├─ slot[name="suffix"] + │ │ └─ span[part="toggle-icon"] + │ └─ div[part="list-wrapper"] // the dropdown + │ ├─ div[part="filter-input"] + │ │ └─ igc-input[part="search-input"] // hidden with disable-filtering or single-select + │ ├─ div[part="header"] + │ │ └─ slot[name="header"] + │ ├─ igc-virtual-scroll#dropdown[part="list"][role="listbox"] + │ │ ├─ igc-combo-header[part="group-header"] // one for each group + │ │ └─ igc-combo-item[part="item"] // one for each option + │ ├─ div[part="empty"] // shown when the list has no options + │ │ └─ slot[name="empty"] + │ └─ div[part="footer"] + │ └─ slot[name="footer"] + └─ igc-validator[part="helper-text"] // the helper text and the validation messages +``` + + + + + +The `igx-combo` element renders its input field in an input group and its dropdown list in an overlay: + +```text +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 {Platform} Combo, follow the [{ProductName} Getting Started](../../general/getting-started.mdx)[{ProductName} Getting Started](../../general-getting-started.mdx) topic for the basic project setup, then add the component for your target platform. + + -First, you need to install the {ProductName} by running the following command: +Install the **{PackageCommon}** package: ```cmd -npm install {PackageWebComponents} +npm install {PackageCommon} ``` -Before using the component, you need to register it together with its additional components and necessary CSS: +Then import the , its theme CSS, and register the component. The registration also registers the input, icon, and popover elements that the Combo renders: ```ts -import { defineComponents, IgcComboComponent } -from 'igniteui-webcomponents'; +import { defineComponents, IgcComboComponent } from 'igniteui-webcomponents'; import 'igniteui-webcomponents/themes/light/bootstrap.css'; defineComponents(IgcComboComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../../general-getting-started.mdx) topic. + + - +Install the **{PackageCommon}** package: +```cmd +npm install {PackageCommon} +``` +Then import the wrapper and the theme CSS: - +```tsx +import { IgrCombo } from 'igniteui-react'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; +``` + + Register the {ProductName} services: @@ -65,9 +191,9 @@ Register the {ProductName} services: builder.Services.AddIgniteUIBlazor(); ``` -Registering , the client resource module of the , is **optional**: the component loads its resources when it first renders. Listing it in `builder.Services.AddIgniteUIBlazor(typeof(IgbComboModule))` can be used to preload resources or to support elements created only on the client (see [Component Modules](../../general-getting-started.mdx#component-modules)). +Registering , the client resource module of the , is **optional**: the component loads its resources when it first renders. Listing it in `builder.Services.AddIgniteUIBlazor(typeof(IgbComboModule))` can be used to preload resources or to support elements created only on the client (see [Component Modules](../../general-getting-started.mdx#component-modules)). -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the app's host page (**wwwroot/index.html** in a standalone Blazor WebAssembly or Blazor Hybrid app, **Pages/_Host.cshtml** in a Blazor Server app, **Components/App.razor** in a Blazor Web App): +Then link the theme CSS file in the app's host page (**wwwroot/index.html** in a standalone Blazor WebAssembly or Blazor Hybrid app, **Pages/_Host.cshtml** in a Blazor Server app, **Components/App.razor** in a Blazor Web App): ```razor @@ -75,65 +201,122 @@ You will also need to link an additional CSS file to apply the styling to the + +If your project doesn't use {ProductName} 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 and its template directives: - +```ts +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: ` + + `, + imports: [IGX_COMBO_DIRECTIVES] +}) +export class HomeComponent { + public cities = [ + { id: 'BG01', name: 'Sofia' }, + { id: 'BG02', name: 'Plovdiv' }, + { id: 'BG03', name: 'Varna' } + ]; +} +``` + + -First, you need to the install the corresponding {ProductName} npm package by running the following command: +After registration, render the Combo and bind its `data` to an array of options. The `valueKey` names the field that identifies an option, and the `displayKey` names the field that the list shows: -```cmd -npm install igniteui-react -``` + -You will then need to import the {Platform} and its necessary CSS: + -```tsx -import { IgrCombo } from 'igniteui-react'; -import 'igniteui-webcomponents/themes/light/bootstrap.css'; +```html + ``` +```ts +const combo = document.getElementById('cities') as IgcComboComponent; - +combo.data = [ + { id: 'BG01', name: 'Sofia' }, + { id: 'BG02', name: 'Plovdiv' }, + { id: 'BG03', name: 'Varna' } +]; +``` + - -The component doesn't work with the standard `
` element. Use `Form` instead. - + -Then, we will bind an array of objects to the combo data source used for building the list of options. +```tsx +const cities = [ + { id: 'BG01', name: 'Sofia' }, + { id: 'BG02', name: 'Plovdiv' }, + { id: 'BG03', name: 'Varna' } +]; - + +``` -```ts -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; +```razor + - constructor() { - this.combo = document.getElementById('basic-combo') as IgcComboComponent; - this.combo.data = cities; +@code { + private class City + { + public string Id { get; set; } + public string Name { get; set; } } + + private List Cities = new() + { + new City { Id = "BG01", Name = "Sofia" }, + new City { Id = "BG02", Name = "Plovdiv" }, + new City { Id = "BG03", Name = "Varna" } + }; } ``` +## Usage + +Use the {Platform} 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 + +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 {Platform} Combo uses the box type by default. Set `outlined` for the border type. The box type is a style of the Material theme: in the Bootstrap, Fluent, and Indigo themes, both types look the same. + + + ```html - + + +``` + + + + + +```tsx + + ``` @@ -141,33 +324,55 @@ export class Sample { ```razor - + + +``` -@code { - private class City { - public string Id { get; set; } - public string Name { get; set; } - public string Country { get; set; } - } + - private List Data = new List { - new City { - Id = "UK01", - Name = "London", - Country = "United Kingdom", - }, - new City { - Id = "BG01", - Name = "Sofia", - Country = "Bulgaria", - }, - new City { - Id = "US01", - Name = "New York", - Country = "United States", - }, - }; -} + + +The Angular Combo uses the box type by default. Set the input to `border` for the border type. Add the label with the `igxLabel` directive and the left icon with an `igx-prefix`: + +```html + + + language + + + + + +``` + + + + + +Add the label with the `label` property, and the left icon in the `prefix` slot. Register the icon first, as described in the [Icon](../../layouts/icon.mdx) topic. + + + + + + + + + + + + + + + +### Disabled States + +Set `disabled` on the {Platform} Combo to show the disabled state of both the border and the box type. + + + +```html + ``` @@ -175,56 +380,85 @@ export class Sample { ```tsx -interface City { - id: string; - name: string; -} + +``` -const cities: City[] = [ - { name: "London", id: "UK01" }, - { name: "Sofia", id: "BG01" }, - { name: "New York", id: "NY01" }, -]; + - + + +```razor + +``` + + + + + +```html + ``` -### 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: + -- `T` - **required**, if is omitted, this should be set to "object", otherwise this needs to match the property type of . -- - **Optional**, **required** for complex data object - Determines which field of the data source will be used to make selections. If is omitted, the selection API will use object references to select items. -- - **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 , the combo will use the specified (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 and respectively. + + + + + + + + +### 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: + +```css +.small { + --ig-size: var(--ig-size-small); +} + +.large { + --ig-size: var(--ig-size-large); +} +``` + + + +The {Platform} Combo is medium by default. + + + + + + + + + + - -When the data source consists of primitive types (e.g. `strings`, `numbers`, etc.), **do not** specify a and/or . - + + + -### Setting Value +### Interaction States -The ComboBox component exposes a 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. +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. -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 . 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 . +Clicking the input field or the toggle opens the dropdown. To open and close the dropdown in code, use the `open` property or the `show`, `hide`, and `toggle` methods`Open` parameter or the `ShowAsync`, `HideAsync`, and `ToggleAsync` methods`open`, `close`, and `toggle` methods: ```ts -const combo = document.getElementById('basic-combo') as IgcComboComponent; +const combo = document.querySelector('igc-combo'); -// Given the overview example from above this will return ['BG01'] -console.log(combo.value); - -// Change the selected items to New York and London -combo.value = ['NY01', 'UK01']; +await combo.show(); +await combo.hide(); +await combo.toggle(); ``` @@ -234,241 +468,948 @@ combo.value = ['NY01', 'UK01']; ```tsx const comboRef = useRef(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']; +comboRef.current.show(); +comboRef.current.hide(); +comboRef.current.toggle(); ``` -### Selection API + -The combo component exposes APIs that allow you to change the currently selected items. +```razor + -Besides selecting items from the list of options by user interaction, you can select items programmatically. This is done via the and 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 for your combo component, then you should pass the value keys of the items you would like to select/deselect: +@code { + private IgbCombo Combo; -#### Select/deselect some items + private async Task OpenAsync() => await Combo.ShowAsync(); +} +``` - + + ```ts -// Select/deselect items by their IDs as valueKey is set to 'id' -combo.select(['BG01', 'BG02', 'BG03', 'BG04']); -combo.deselect(['BG01', 'BG02', 'BG03', 'BG04']); +@ViewChild(IgxComboComponent, { static: true }) +public combo: IgxComboComponent; + +public openCombo(): void { + this.combo.open(); +} +``` + + + +The following sample shows the states side by side. Because hover and focus come from the pointer and the keyboard, the sample styles the display-only combos for these states with CSS classes. + + + + + + + + + + + + + +### 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](../../input-group.mdx)[Input](../input.mdx) and equipped for sophisticated designs that display success, warn, and error visuals. + + + +The {Platform} Combo is form-associated. Set `required` to require at least one selected item, and `invalid` to show the error state. Put the guidance or the error message in the `helper-text` slot. The Combo also exposes the `checkValidity`, `reportValidity`, and `setCustomValidity` methods of the constraint validation API. The Combo has no built-in success or warn state, so the sample styles these two states with CSS classes. + + + + + +```html + + Please select a different region + ``` + + +```tsx + + Please select a different region + +``` + + ```razor - + + Please select a different region +``` -@code { - private List Data; - private IgbCombo Combo; - private object[] Cities; + - protected override void OnInitialized() { - this.Data = SampleData.Cities; - this.Cities = new object[] { "UK01", "UK02", "UK03", "UK04", "UK05" }; - } + - public void SelectCities() { - this.Combo.Select(Cities); - } +The Angular Combo takes its validation state from the form control that it is bound to, through `ngModel` or a reactive form. Set the property to an `IgxInputState` value to set the state in code. Put the guidance or the error message in an `igx-hint`: - public void DeselectCities() { - this.Combo.Deselect(Cities); - } -} +```html + + Please select a different region + ``` + - + + -```tsx -// 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"]); + + + + + + +### Dropdown Size + +The Dropdown used for the Combo comes with the appropriate sizing for Large, Medium and Small Combo similarly to the normal [Dropdown](../../drop-down.mdx)[Dropdown](../dropdown.mdx) component. The dropdown takes its size from the Combo, so set the `--ig-size` variable on the Combo. + + + +The Angular Combo also exposes the and inputs for the height of the items and of the list: + +```html + ``` +The following sample shows the dropdowns only, without their input fields. + + + + + + + + -#### Select/deselect all items + + + + +### Dropdown Search Input + +The dropdown of the {Platform} Combo contains a search input that filters the options as users type. + + + +Set the text of the empty search input with `placeholderSearch`, show a button that toggles case-sensitive filtering with `caseSensitiveIcon`, and hide the search input with `disableFiltering`. The `filteringOptions` object sets the key that the search filters by, and whether the filtering is case-sensitive and matches diacritics: + + +```html + +``` ```ts -// Select/deselect all items -combo.select(); -combo.deselect(); +combo.filteringOptions = { filterKey: 'name', caseSensitive: false, matchDiacritics: true }; ``` + + +```tsx + +``` + + ```razor -@code { - public void SelectAll() { - this.Combo.Select(new object[] {}); - } + +``` - public void DeselectAll() { - this.Combo.Deselect(new object[] {}); - } -} + + + + +Set the text of the empty search input with , show a button that toggles case-sensitive filtering with , and hide the search input with . The input sets the key that the search filters by and whether the filtering is case-sensitive: + +```html + + ``` +The following sample shows the search input only. Because its states come from the pointer and the keyboard, the sample styles the display-only search inputs with CSS classes. - + + + + + + + + + + + + +### Data Binding + +The {Platform} 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: + + +- - the field that identifies an option. The value and the selection API of the Combo use it. When you omit it, the Combo uses references to the objects. +- - the field that the list and the input field show. When you omit it, the Combo uses the `valueKey`. +- - the field that groups the options. Each group gets a header, and sorts the groups in ascending or descending order. + + + + + +- - the field that identifies an option. The value and the selection API of the Combo use it. When you omit it, the Combo uses references to the objects. +- - the field that the list and the input field show. When you omit it, the Combo uses the `ValueKey`. +- - the field that groups the options. Each group gets a header, and sorts the groups in ascending or descending order. + +The `T` type parameter of the Blazor Combo is the type of its values. Set it to the type of the `ValueKey` field, or to the type of the options when you don't set a `ValueKey`. When you bind the `Value` with `@bind-Value`, Razor infers `T` from the bound field. + + + + + +- - 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. +- - the field that the list and the input field show. When you omit it, the Combo uses the `valueKey`. +- - the field that groups the options. Each group gets a header, and sorts the groups. + +To bind to data that loads from a remote service, see the [Remote Binding](../../combo-remote.mdx) 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 {Platform} Combo exposes its selected items through its value, and methods that select and deselect items in code. + + + +The `value` holds the selected items as their `valueKey` values, or as object references when there is no `valueKey`. Set it to select items when the Combo first renders. The `select` and `deselect` methods take an array of items; called without items, they select or deselect all items: + + + + + +```ts +// select and deselect items by their ids, because the valueKey is 'id' +combo.select(['BG01', 'BG02']); +combo.deselect(['BG01']); + +// select and deselect all items +combo.select(); +combo.deselect(); + +console.log(combo.value); // the ids of the selected items +``` + + + + ```tsx -// Select/deselect all items +// select and deselect items by their ids, because the valueKey is 'id' +comboRef.current.select(['BG01', 'BG02']); +comboRef.current.deselect(['BG01']); + +// select and deselect all items comboRef.current.select([]); comboRef.current.deselect([]); + +console.log(comboRef.current.value); // the ids of the selected items ``` + -If the property is omitted, you will have to list the items you wish to select/deselect as objects references: +```razor +@code { + private IgbCombo Combo; + public void SelectCities() => Combo.Select(new object[] { "BG01", "BG02" }); - + public void DeselectAll() => Combo.Deselect(new object[] { }); +} +``` + + + + + +To let users select a single item and type in the input field to filter the list, use the [Single Selection](./single-selection.mdx) mode. + + + + +The Angular Combo supports two-way binding with `[(ngModel)]` and works in template-driven and reactive forms. The property returns the selected items, and the , , , and methods change it: + +```html + +``` ```ts -// Select/deselect values by object references when no valueKey is provided -combo.select([cities[1], cities[5]]); -combo.deselect([cities[1], cities[5]]); +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 before the selection changes, which you can cancel, and after the selection is committed. + +To let users select a single item and type in the input field, use the [Simple Combo](./single-selection.mdx). + +### 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. -```tsx -// 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]]); -``` + + + +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 {Platform} Combo exposes the following properties. See the API reference for the complete type definitions. + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `T[]` | `[]` | The options of the Combo. | +| | `string` | — | The field that identifies an option. | +| | `string` | — | The field that the list and the input field show. Falls back to the `valueKey`. | +| | `string` | — | The field that groups the options. | +| | `'asc' \| 'desc' \| 'none'` | `'asc'` | How the groups are sorted. | +| | `ComboValue[]` | `[]` | The selected items, as their `valueKey` values or as object references. | +| | `string` | — | The label of the Combo. | +| | `string` | — | The text that the input field shows when no item is selected. | +| | `string` | — | The text that the empty search input shows. | +| | `boolean` | `false` | Whether the Combo uses the border type. | +| | `boolean` | `false` | Whether users select a single item and filter the list from the input field. | +| `open` | `boolean` | `false` | Whether the dropdown is open. | +| `disabled` | `boolean` | `false` | Whether the Combo is disabled. | +| `required` | `boolean` | `false` | Whether the Combo requires a selected item to be valid. | +| `invalid` | `boolean` | `false` | Whether the Combo shows its invalid state. | +| | `boolean` | `false` | Whether the search input is hidden. | +| | `boolean` | `false` | Whether the search input shows the button that toggles case-sensitive filtering. | +| | `FilteringOptions` | — | The key that the search filters by, and whether the filtering is case-sensitive and matches diacritics. | +| | `boolean` | `false` | Whether the clear button is hidden. | +| | `boolean` | `false` | Whether the list, instead of the search input, takes the focus when the dropdown opens. | +| | `T[]` | — | Read-only. The selected items as objects from the `data`. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `object` | — | The options of the Combo. | +| | `string` | — | The field that identifies an option. | +| | `string` | — | The field that the list and the input field show. Falls back to the `ValueKey`. | +| | `string` | — | The field that groups the options. | +| | `T[]` | — | The selected items. | +| | `string` | — | The label of the Combo. | +| | `string` | — | The text that the input field shows when no item is selected. | +| | `string` | — | The text that the empty search input shows. | +| | `bool` | `false` | Whether the Combo uses the border type. | +| | `bool` | `false` | Whether users select a single item and filter the list from the input field. | +| | `bool` | `false` | Whether the dropdown is open. | +| | `bool` | `false` | Whether the Combo is disabled. | +| | `bool` | `false` | Whether the Combo requires a selected item to be valid. | +| | `bool` | `false` | Whether the Combo shows its invalid state. | +| | `bool` | `false` | Whether the search input is hidden. | +| | `bool` | `false` | Whether the search input shows the button that toggles case-sensitive filtering. | +| | `bool` | `false` | Whether the clear button is hidden. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `any[]` | — | The options of the Combo. | +| | `string` | — | The field that identifies an option. | +| | `string` | — | The field that the list and the input field show. Falls back to the `valueKey`. | +| | `string` | — | The field that groups the options. | +| | `IgxInputGroupType` | `'box'` | The type of the input field: `box`, `border`, or `line`. | +| | `string` | — | The text that the input field shows when no item is selected. | +| | `string` | — | The text that the empty search input shows. | +| | `boolean` | `false` | Whether the Combo is disabled. | +| | `boolean` | `false` | Whether the search input is hidden. | +| | `boolean` | `false` | Whether the search input shows the button that toggles case-sensitive filtering. | +| | `IComboFilteringOptions` | — | The key that the search filters by and whether the filtering is case-sensitive. | +| | `boolean` | `false` | Whether users can add the text of the search input as a new item. | +| | `boolean` | `false` | Whether the clear button is hidden. | +| | `boolean` | `true` | Whether the search input takes the focus when the dropdown opens. | +| | `number` | — | The height of the items in the list. | +| | `number` | — | The maximum height of the list. | +| | `IgxInputState` | `INITIAL` | The validation state of the Combo. | +| | `any[]` | — | Read-only. The selected items. | + + + +## Methods + +The {Platform} Combo exposes the following methods. + + + +| Method | Description | +| --- | --- | +| | Selects the items that you pass, by their `valueKey` values or by reference. Selects all items when you pass none. | +| | Deselects the items that you pass, by their `valueKey` values or by reference. Deselects all items when you pass none. | +| `show` | Opens the dropdown. | +| `hide` | Closes the dropdown. | +| `toggle` | Opens the dropdown when it is closed, and closes it when it is open. | +| `checkValidity` | Returns whether the Combo satisfies its validation constraints. | +| `reportValidity` | Checks the validity of the Combo and shows its invalid state when it fails. | + + +| Method | Description | +| --- | --- | +| | Selects the items that you pass. Selects all items when you pass an empty array. | +| | Deselects the items that you pass. Deselects all items when you pass an empty array. | +| | Opens the dropdown. | +| | Closes the dropdown. | +| | Opens the dropdown when it is closed, and closes it when it is open. | - + + +| Method | Description | +| --- | --- | +| | Selects the items that you pass. Pass `true` as the second argument to clear the current selection first. | +| | Deselects the items that you pass. | +| | Selects all items. Pass `true` to ignore the current filter. | +| | Deselects all items. Pass `true` to ignore the current filter. | +| | Opens the dropdown. | +| | Closes the dropdown. | +| | Opens the dropdown when it is closed, and closes it when it is open. | + -### Validation +## Events -The {ProductName} component supports most of the properties, such as , , , , etc. The component also exposes two methods bound to its validation: +The {Platform} Combo emits the following events. -- - checks for validity and returns true if the component satisfies the validation constraints. -- - a wrapper around reportValidity to comply with the native input API. + -## Keyboard Navigation +| Name | Description | +| --- | --- | +| `igcChange` | Emitted before the user changes the selection. The event detail holds the new value, the changed items, and the type of the change. Cancel the event to keep the selection. | +| `igcOpening` | Emitted before the user opens the dropdown. Cancelable. | +| `igcOpened` | Emitted after the dropdown opens on a user action. | +| `igcClosing` | Emitted before the user closes the dropdown. Cancelable. | +| `igcClosed` | Emitted after the dropdown closes on a user action. | -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**: +| Name | Description | +| --- | --- | +| | Emitted with before the selection changes. Set `cancel` to keep the selection. | +| | Emitted with after the selection is committed. | +| | Emitted before the dropdown opens. Cancelable. | +| | Emitted after the dropdown opens. | +| | Emitted before the dropdown closes. Cancelable. | +| | Emitted after the dropdown closes. | +| | Emitted when the text of the search input changes. | +| | Emitted before users add a custom value to the list. | -- 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 -You can change the appearance of the component and its items, by using the exposed CSS parts listed below: - -| 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. | - - -Using the CSS parts we have full control over the Combo 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 {Platform} 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. + + + +The `igc-combo` element exposes the following CSS parts: + +| Part | What it styles | +| --- | --- | +| `input` | The input field. | +| `native-input` | The native input of the input field. | +| `label` | The label. | +| `prefix` | The container of the `prefix` slot. | +| `suffix` | The container of the `suffix` slot. | +| `toggle-icon` | The toggle button. `filled` is added when the Combo has a value. | +| `clear-icon` | The clear button. | +| `helper-text` | The helper text. | +| `list-wrapper` | The dropdown. | +| `filter-input` | The container of the search input. | +| `search-input` | The search input. | +| `case-icon` | The button that toggles case-sensitive filtering. `active` is added while it is on. | +| `header` | The container of the `header` slot. | +| `list` | The list of options. | +| `group-header` | Each group header in the list. | +| `item` | Each option in the list. `active` and `selected` are added to the active and the selected options. | +| `checkbox` | The checkbox of each option. `checked` is added when the option is selected. | +| `checkbox-indicator` | The indicator of the checkbox of each option. | +| `empty` | The container of the `empty` slot. | +| `footer` | The container of the `footer` slot. | -```css -igc-combo::part(search-input) { - background-color: var(--ig-gray-100); - border-radius: 2px; + + +### 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. + + + +```scss +@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](../../overlay-styling.mdx) topic. + + + + + +The Sass functions come from the `igniteui-theming` package. See the [Theming](../../themes/overview.mdx) topic for the Sass setup. + +```scss +@use "igniteui-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 +); + +:root { + @include tokens($custom-combo-theme); + @include tokens($custom-drop-down-theme); + @include tokens($custom-checkbox-theme); } +``` + + -igc-combo::part(input) { - background-color: var(--ig-gray-100); +### CSS Variables + +Set the CSS variables on a Combo or on a container when you need local styling without a Sass build step: + +```css +.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; } +``` -igc-combo::part(prefix) { - background-color: var(--ig-secondary-50); - color: var(--ig-primary-500); + + +Use the CSS parts for other styles: + +```css +igc-combo::part(group-header) { + color: #005dcc; } -igc-combo::part(toggle-icon) { - color: var(--ig-primary-500); +igc-combo::part(item selected) { + color: #000; } ``` - + + + + + + + + + + + + + + +### Styling with Tailwind + +You can style the {Platform} Combo using our custom Tailwind utility classes. Make sure to [set up Tailwind](../../themes/misc/tailwind-classes.mdx)[set up Tailwind](../../themes/tailwind.mdx) first. + + + +Import the Ignite UI utilities in your global stylesheet: + +```css +@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: + +```html + + ... + +``` + +The exclamation mark (`!`) gives the Tailwind utility precedence over the default theme styles of the Combo. + + + + + +Set the `--ig-combo-*`, `--ig-input-group-*`, and `--ig-drop-down-*` CSS variables with Tailwind arbitrary properties: + + + + + +```html + + +``` + + + + + +```tsx + +``` + + + + + +```razor + +``` + + + + + + + + + + + + + + + +## Accessibility + +The {Platform} 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 {Platform} Combo is a tab stop. When the dropdown opens, the search input takes the focus, or the list when `autofocusList` is set or the search input is hidden. In the single selection mode, the focus stays in the input field. The following keys work while the Combo has the focus: + +| Key | Action | +| --- | --- | +| Arrow Down | In the input field, opens the dropdown, and in the single selection mode also moves the focus to the list and activates the first option. In the search input, moves the focus to the list and activates the first option. In the list, activates the next option. | +| Alt + Arrow Down | In the input field, does the same as Arrow Down. | +| Arrow Up | In the input field, closes the dropdown. In the search input, closes the dropdown and moves the focus to the input field. In the list, activates the previous option. From the first option, moves the focus to the search input, or closes the dropdown and moves the focus to the input field when the search input is hidden. | +| Home / End | In the list, activates the first or the last option. | +| Space | In the list, selects or deselects the active option. | +| Enter | With an active option, closes the dropdown and moves the focus to the input field. In the single selection mode, also selects the active option. | +| Escape | When the dropdown is open, closes it and moves the focus to the input field. When the dropdown is closed, clears the selection. | +| Tab / Shift + Tab | Closes the dropdown and moves the focus to the next or the previous focusable element. In the single selection mode, also selects the active option. | + +A disabled Combo ignores these keys. + + + + + +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 {Platform} Combo renders the following roles and attributes: +| Element | Role | Attributes | +| --- | --- | --- | +| The input field | `combobox` | `aria-haspopup="listbox"`, `aria-expanded`, `aria-disabled`, `aria-controls` that points to the list, and, with a helper text, `aria-describedby` that points to it | +| The `list` part | `listbox` | `aria-multiselectable` (`false` in the single selection mode), `aria-labelledby` that points to the input field, and `aria-activedescendant` that points to the active option | +| Each `item` part | `option` | `aria-selected`, `aria-posinset`, and `aria-setsize` | +| The `clear-icon` part | `button` | `aria-label` from the resource strings | + +The {Platform} Combo also behaves as follows for assistive technology: + +- The input field takes its accessible name from the `label`. Without a label, it gets a name from the resource strings that says whether options are selected. +- The active option is announced through `aria-activedescendant` while the focus stays in the list. +- The content of the closed dropdown is `inert`. + + + + + +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 input. Without them, it gets a name from the resource strings that says whether options are selected. + + + +### Accessibility Compliance + +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../../interactivity/accessibility-compliance.mdx) topic. + +| Criterion | How the component complies | +| --- | --- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | The `combobox`, `listbox`, and `option` roles expose the structure, and the list is labeled by the `igxLabel` or the `ariaLabelledBy` elementthe input field. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | The arrow keys open the dropdown and move through the options, and Space selects the active option. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap) | Tab closes the dropdown and moves the focus out of the Combo. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/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](#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](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast) requires. +- Show the error message in the helper text, not by color alone. See [Validation States](#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 show `undefined`. When the `valueKey` field of an object is `undefined`, 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](../../layouts/virtual-scroll.mdx#known-limitations), so its limitations apply. The list renders only the options in view, and code that queries the DOM finds only those options. + + ## API References +The {Platform} Combo API reference lists the complete API surface for the target platform. + + + +- + + + + + +- + + + + + +- +- +- +- +- + + + +## Dependencies + +The {Platform} Combo requires a theme to apply its colors and sizes. See the framework-specific setup in [**Getting Started**](../../general/getting-started.mdx)[**Getting Started**](../../general-getting-started.mdx). + + + +The Angular Combo uses the Drop Down, the Input Group, the Checkbox, the Icon, and the Overlay. Their themes style its parts: + +- +- +- +- +- + + + + + +The registration of the `IgcComboComponent` also registers the input, icon, checkbox, and popover elements that the Combo renders. Register the components that you place in the slots of the Combo, such as the Icon, separately. + + + + + +The Blazor Combo and the components that you place in its slots, such as the Icon, load their modules when they first render. See [Component Modules](../../general-getting-started.mdx#component-modules). -
+ ## Additional Resources +The following resources provide more {Platform} Combo guidance and project support: + + + +- [Combo Features](../../combo-features.mdx) +- [Combo Remote Binding](../../combo-remote.mdx) +- [Combo Templates](./templates.mdx) + + + + + +- [Combo Features](./features.mdx) +- [Combo Templates](./templates.mdx) +- [Combo Single Selection](./single-selection.mdx) + + + +- [Combo - Design System Component](https://www.infragistics.com/products/indigo-design/help/components/combo) - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +The {Platform} Combo lets users search a list and select one or more options. Use these components when the selection works differently: + +- [Select](../../select.mdx)[Select](../select.mdx) - Use Select when users pick a single option from a short list that doesn't need search. +- [Dropdown](../../drop-down.mdx)[Dropdown](../dropdown.mdx) - Use Dropdown to show a list of actions or options from a button or another element. +- [Simple Combo](./single-selection.mdx) - 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 {Platform} 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`.Set the `value` of the {Platform} Combo to an array of `valueKey` values, or call the `select` method with the items. Without a `valueKey`, the {Platform} 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.Yes. Set `singleSelect` on the {Platform} Combo, and users select one item and filter the list from the input field instead of the search input. See the Single Selection topic. + + + Set the `groupKey` of the {Platform} Combo to the field that holds the group of each option. The {Platform} Combo shows a header for each group and sorts the groups. + + + Use the {Platform} Combo when the list is long, users need to search it, or they select more than one option. Use the {Platform} Select for a short list from which users pick a single option without searching. + + diff --git a/docs/xplat/src/content/en/components/inputs/combo/single-selection.mdx b/docs/xplat/src/content/en/components/inputs/combo/single-selection.mdx index cb9fecab8d..aefce5482c 100644 --- a/docs/xplat/src/content/en/components/inputs/combo/single-selection.mdx +++ b/docs/xplat/src/content/en/components/inputs/combo/single-selection.mdx @@ -1,37 +1,303 @@ --- -title: "{Platform} ComboBox Component – {ProductName}" -description: "{Platform} Combo component provides a powerful input, combining features of the basic HTML input, select, filtering and custom drop-down lists. Try it for FREE" -keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} ComboBox component" +title: "{Platform} Single Selection Combo Component" +description: "The {ProductName} Single Selection Combo is a Combo in which users select one option and filter the searchable dropdown list by typing in the input field." +keywords: "{Platform} Single Selection Combo, {ProductName}, single select combo, simple combo, combobox, searchable dropdown, combo filtering" license: MIT -mentionedTypes: ["Combo", "SingleSelect", "ComboItem", "ComboHeader", "ComboList"] +last_updated: "2026-11-05" +relatedComponents: ["Combo", "Select", "Dropdown"] +mentionedTypes: ["Combo", "ComboItem", "ComboHeader", "ComboList"] llms: - description: "The {Platform} ComboBox supports single-selection mode and quick filtering of the list of items via the main input prompt." + description: "The {ProductName} Single Selection Combo is a Combo in which users select one option and filter the searchable dropdown list by typing in the input field." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import DoDont from 'igniteui-astro-components/components/mdx/DoDont.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import comboAnatomy from '@xplat-images/anatomy-content-light/single-select-combo-lt-a.png'; +import comboDoAlignment from '@xplat-images/combo/single-select-combo-do-1.png'; +import comboDoNotAlignment from '@xplat-images/combo/single-select-combo-do-not-1.png'; +# Single Selection Combo -# {Platform} Single Selection ComboBox +The {ProductName} Single Selection Combo is a Combo in which users select one option and filter the searchable dropdown list by typing in the input field. -The {Platform} `ComboBox` supports single-selection mode and quick filtering of the list of items via the main input prompt. Users can quickly type in the item they are looking for and be presented with a list of options. Upon pressing the enter key, the first highlighted match will be selected. + -## {Platform} Single Selection Example +The Angular single selection Combo is the Simple Combo, the `igx-simple-combo` component. It binds, groups, and templates its options like the Combo, and lets users type in the input field to filter the list or to enter a custom value. -To enable single-selection and quick filtering, set the property on the . The user experience and keyboard navigation will mostly stay the same, but instead of having to type in your search query into a special filtering box above the list of options, the main input box will be used. + + + + +Set on the {Platform} Combo to switch it to single selection. The input field becomes editable and filters the list as users type, the search input of the dropdown is hidden, and the options show no checkboxes. + + + + +The Combo has two layout options: Combo with Single Select (Simple Combo) and Combo (Multiple Select). + + +## Live Demo + + + + + + + + + + + + + +## Anatomy + +The Simple Combo has two pieces: an Input containing the current selection or a placeholder, and a Dropdown that is shown in order to select an option from a predefined dropdown list. + + + + + +1. Input Container: displays the value and input elements
+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. Dropdown Header: used to group or describe the dropdown options
+8. Selected Item: selected Item from the Dropdown List
+9. Dropdown List: displays the list of selectable options + + + +In the single selection mode, the `igc-combo` element renders an editable input field, hides the search input of the dropdown, and renders the options without checkboxes: + +```text +igc-combo[single-select] +└─ #shadow-root + ├─ igc-popover + │ ├─ igc-input#target[slot="anchor"] // the editable input field, exported as the "input" part + │ │ ├─ slot[name="prefix"] + │ │ ├─ span[part="clear-icon"] // shown when the Combo has a value + │ │ ├─ slot[name="suffix"] + │ │ └─ span[part="toggle-icon"] + │ └─ div[part="list-wrapper"] // the dropdown + │ ├─ div[part="filter-input"][hidden] // the search input is hidden + │ ├─ div[part="header"] + │ │ └─ slot[name="header"] + │ ├─ igc-virtual-scroll#dropdown[part="list"][role="listbox"] + │ │ ├─ igc-combo-header[part="group-header"] // one for each group + │ │ └─ igc-combo-item[part="item"][hide-checkbox] // one for each option + │ ├─ div[part="empty"] // shown when the list has no options + │ │ └─ slot[name="empty"] + │ └─ div[part="footer"] + │ └─ slot[name="footer"] + └─ igc-validator[part="helper-text"] // the helper text and the validation messages +``` + + + + + +The `igx-simple-combo` element renders an editable input field in an input group and its dropdown list in an overlay. It has no search input: + +```text +igx-simple-combo +├─ igx-input-group +│ ├─ [igxLabel] +│ ├─ igx-prefix +│ ├─ input[igxInput][role="combobox"] // editable, filters the list +│ ├─ igx-suffix.igx-combo__clear-button // shown when the Combo has a value +│ ├─ igx-suffix // the case-sensitive icon, shown with showSearchCaseIcon +│ ├─ 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 + ├─ [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 {Platform} Single Selection Combo, follow the [{ProductName} Getting Started](../../general/getting-started.mdx)[{ProductName} Getting Started](../../general-getting-started.mdx) topic for the basic project setup, then add the component for your target platform. + + + +The single selection mode is a mode of the Combo, so the package, the registration, and the theme CSS are the ones of the [Combo](./overview.mdx#getting-started). + + +Install the **{PackageCommon}** package: + +```cmd +npm install {PackageCommon} +``` + +Then import the , its theme CSS, and register the component: + +```ts +import { defineComponents, IgcComboComponent } from 'igniteui-webcomponents'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; + +defineComponents(IgcComboComponent); +``` + +Render the Combo with the `single-select` attribute and bind its `data`: + ```html - + +``` + +```ts +const combo = document.getElementById('countries') as IgcComboComponent; + +combo.data = [ + { id: 'BY', name: 'Belarus' }, + { id: 'BE', name: 'Belgium' }, + { id: 'BG', name: 'Bulgaria' } +]; +``` + + + + + +Install the **{PackageCommon}** package: + +```cmd +npm install {PackageCommon} +``` + +Then import the wrapper and the theme CSS, and render the Combo with `singleSelect`: + +```tsx +import { IgrCombo } from 'igniteui-react'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; + +const countries = [ + { id: 'BY', name: 'Belarus' }, + { id: 'BE', name: 'Belgium' }, + { id: 'BG', name: 'Bulgaria' } +]; + + ``` +Register the {ProductName} services: + +```csharp +// in Program.cs file + +builder.Services.AddIgniteUIBlazor(); +``` + +Registering , the client resource module of the , is **optional**: the component loads its resources when it first renders. See [Component Modules](../../general-getting-started.mdx#component-modules). + +Then link the theme CSS file in the app's host page, and render the Combo with `SingleSelect`: + +```razor + +``` + ```razor - + + +@code { + private class Country + { + public string Id { get; set; } + public string Name { get; set; } + } + + private List Countries = new() + { + new Country { Id = "BY", Name = "Belarus" }, + new Country { Id = "BE", Name = "Belgium" }, + new Country { Id = "BG", Name = "Bulgaria" } + }; +} +``` + + + + + +If your project doesn't use {ProductName} yet, run `ng add igniteui-angular`. Then import the `IGX_SIMPLE_COMBO_DIRECTIVES` token and add it to the `imports` of your component. The token holds the and its template directives: + +```ts +import { Component } from '@angular/core'; +import { IGX_SIMPLE_COMBO_DIRECTIVES } from 'igniteui-angular/simple-combo'; +// import { IGX_SIMPLE_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular/simple-combo'; for licensed package + +@Component({ + selector: 'app-home', + template: ` + + `, + imports: [IGX_SIMPLE_COMBO_DIRECTIVES] +}) +export class HomeComponent { + public countries = [ + { id: 'BY', name: 'Belarus' }, + { id: 'BE', name: 'Belgium' }, + { id: 'BG', name: 'Bulgaria' } + ]; +} +``` + + + +## Usage + +Use the {Platform} Single Selection Combo when users pick exactly one option from a list that they need to search, such as a country or a city. + +### Type + +The Simple 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 {Platform} Combo uses the box type by default. Set `outlined` for the border type. The box type is a style of the Material theme: in the Bootstrap, Fluent, and Indigo themes, both types look the same. + + + + + +```html + + ``` @@ -39,129 +305,1193 @@ To enable single-selection and quick filtering, set the ```tsx - + + +``` + + + + + +```razor + + ``` - + +The Angular Simple Combo uses the box type by default. Set the input to `border` for the border type. Add the label with the `igxLabel` directive and the left icon with an `igx-prefix`: +```html + + + language + + + + + +``` -## Selection API + -The selection API for a ComboBox with the property applied mostly remains the same, however, there are some important differences compared to ComboBoxes that don't have this property set. + -The main difference is that only one item can be selected at any time. For example, if you have specified a for your combo component, passing more than one item to the / methods will have no effect. This also means that any previously selected items will automatically get deselected upon making a new selection. +Add the label with the `label` property, and the left icon in the `prefix` slot. Register the icon first, as described in the [Icon](../../layouts/icon.mdx) topic. -Here's how to select/deselect an item programmatically in a single selection combo. + -### Selecting items + + - + + -```ts -// select the item matching the 'BG01' value of the value key field. -combo.select('BG01'); + + + + +### Disabled States + +Set `disabled` on the {Platform} Single Selection Combo to show the disabled state of both the border and the box type. + + + +```html + ``` + + +```tsx + +``` + + ```razor - + +``` -@code { - private IgbCombo Combo; + - this.Combo.Select(new object[] { "UK01" }); -} + + +```html + ``` + - + + + + -```tsx -// select the item matching the 'BG01' value of the value key field. -comboRef.current.select('BG01'); + + + + +### 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: + +```css +.small { + --ig-size: var(--ig-size-small); +} + +.large { + --ig-size: var(--ig-size-large); +} ``` + + +The {Platform} Combo is medium by default. + + -To deselect an item without making a new selection, call the method. + -#### Deselecting items + + - + + + + +### 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, and typing in the input field opens it and filters the list. To open and close the dropdown in code, use the `open` property or the `show`, `hide`, and `toggle` methods`Open` parameter or the `ShowAsync`, `HideAsync`, and `ToggleAsync` methods`open`, `close`, and `toggle` methods: + + ```ts -// deselect the item matching the 'BG01' value of the value key field. -combo.deselect('BG01'); +const combo = document.querySelector('igc-combo'); + +await combo.show(); +await combo.hide(); +await combo.toggle(); ``` + + +```tsx +const comboRef = useRef(null); + +comboRef.current.show(); +comboRef.current.hide(); +comboRef.current.toggle(); +``` + + ```razor - + @code { - private IgbCombo Combo; + private IgbCombo Combo; + + private async Task OpenAsync() => await Combo.ShowAsync(); +} +``` + + + + - this.Combo.Deselect(new object[] { "UK01" }); +```ts +@ViewChild(IgxSimpleComboComponent, { static: true }) +public combo: IgxSimpleComboComponent; + +public openCombo(): void { + this.combo.open(); } ``` +The following sample shows the states side by side. Because hover and focus come from the pointer and the keyboard, the sample styles the display-only combos for these states with CSS classes. + + + + + + + + + + + + + +### 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](../../input-group.mdx)[Input](../input.mdx) and equipped for sophisticated designs that display success, warn, and error visuals. + + + +The {Platform} Combo is form-associated. Set `required` to require a selected item, and `invalid` to show the error state. Put the guidance or the error message in the `helper-text` slot. In the single selection mode, the form value is the `valueKey` value of the selected item. The Combo has no built-in success or warn state, so the sample styles these two states with CSS classes. + + + + + +```html + + Please select a different region + +``` + + +```tsx + + Please select a different region + +``` + + + + + +```razor + + Please select a different region + +``` + + + + + +The Angular Simple Combo takes its validation state from the form control that it is bound to, through `ngModel` or a reactive form. Set the property to an `IgxInputState` value to set the state in code. Put the guidance or the error message in an `igx-hint`: + +```html + + Please select a different region + +``` + + + + + + + + + + + + + + + +### Dropdown Size + +The Dropdown used for the Combo comes with the appropriate sizing for Large, Medium and Small Combo similarly to the normal [Dropdown](../../drop-down.mdx)[Dropdown](../dropdown.mdx) component. The dropdown takes its size from the Combo, so set the `--ig-size` variable on the Combo. + + + +The Angular Simple Combo also exposes the and inputs for the height of the items and of the list: + +```html + +``` + + + +The following sample shows the dropdowns only, without their input fields. + + + + + + + + + + + + + +### Dropdown Items + +The Dropdown used for the Simple Combo supports two types of items: header and single select item. Both are available in Large, Medium and Small sizes. Through headers, it is possible to organize items in groups. + +Set `groupKey` to the field that holds the group of each option, and the {Platform} Single Selection Combo shows a header for each group. The options of the single selection mode show no checkboxes. To change the content of the items and the headers, see the [Combo Templates](./templates.mdx) topic. + + + +```html + +``` + + + + ```tsx -// deselect the item matching the 'BG01' value of the value key field. -comboRef.current.deselect('BG01'); + +``` + + + + + +```razor + ``` + + +```html + +``` -## Disabled features + -Naturally, some configuration options will have no effect in a single selection ComboBox. +The following sample shows a header and an item in each size. -### Placeholder + -Assigning a value to the property will yield no result since the filtering input that usually is placed above the list of options will not be present in a single selection ComboBox. + -### Auto-focusing the list of options + -Setting the option on a single selection ComboBox will also have no effect. + -## Keyboard Navigation + -The keyboard navigation should behave the same as with a non-single selection ComboBox, except for the fact that now the main input plays the role of a filtering prompt and so all keyboard actions that apply to the filtering/search input are moved to the main input prompt. + -## Other Features +### Dropdown Items States -All other features will behave the same as in a non-single selection ComboBox component. +An item of the {Platform} Single Selection Combo dropdown is idle, hovered, or focused, and each of these states has a selected variant. The drop-down theme also has colors for a disabled item. +The following sample shows the states side by side. Because hover and focus come from the pointer and the keyboard, the sample styles the display-only items for these states with CSS classes. -## API References - -## Additional Resources + -- [{ProductName} **Forums**]({ForumsLink}) -- [{ProductName} **GitHub**]({GithubLink}) + + + + + + + + + + +### Data Binding + +The {Platform} Single Selection Combo binds its options the way the Combo does: bind `data` to an array, and set `valueKey`, `displayKey`, and `groupKey` when the array holds objects. See [Data Binding](./overview.mdx#data-binding) in the Combo topic. + + + +The Angular Simple Combo also binds to a remote service and loads its data on demand. Bind `data` to the loaded chunk, and handle the event to load the next chunk, as the [Combo Remote Binding](../../combo-remote.mdx) topic describes. + + + +### Value and Selection + +The {Platform} Single Selection Combo holds one selected item, and exposes it through its value and its selection API. + + + +The `value` holds the selected item as an array with one element: its `valueKey` value, or the object reference when there is no `valueKey`. Set it to select an item when the Combo first renders. The `select` method selects a single item and deselects the previous one, so pass one item; the `deselect` method deselects it. Called without an item, `select` clears the selection in the single selection mode: + + + + + +```ts +// select the item matching the 'BG' value of the value key field +combo.select('BG'); + +// deselect it +combo.deselect('BG'); + +console.log(combo.value); // ['BG'] while Bulgaria is selected, [] after the deselection +``` + + + + + +```tsx +// select the item matching the 'BG' value of the value key field +comboRef.current.select('BG'); + +// deselect it +comboRef.current.deselect('BG'); + +console.log(comboRef.current.value); // ['BG'] while Bulgaria is selected, [] after the deselection +``` + + + + + +```razor + + +@code { + private IgbCombo Combo; + + public void SelectBulgaria() => Combo.Select(new object[] { "BG" }); + + public void DeselectBulgaria() => Combo.Deselect(new object[] { "BG" }); +} +``` + + + + + +The Combo emits `igcChange``onChange``Change` before the user changes the selection. Its detail holds the new value, the changed items, and the type of the change, and canceling it keeps the selection. + + + + + +The Angular Simple Combo supports two-way binding with `[(ngModel)]` and works in template-driven and reactive forms. The bound value is a single item: its `valueKey` value, or the object reference when there is no `valueKey`. The property returns the selected item, the method selects an item, and the method clears the selection: + +```html + +``` + +```ts +export class CountriesComponent { + @ViewChild(IgxSimpleComboComponent, { static: true }) + public combo: IgxSimpleComboComponent; + + public selectedCountry = 'BG'; + + public selectBelgium(): void { + this.combo.select('BE'); + } + + public clear(): void { + this.combo.deselect(); + } +} +``` + +The Angular Simple Combo emits before the selection changes, and after it. The event arguments hold the old and the new value, the old and the new item, and the display text of the input field, and setting `cancel` in `selectionChanging` keeps the selection: + +```html + +``` + +```ts +public onCountryChanging(event: ISimpleComboSelectionChangingEventArgs): void { + if (event.newValue === 'BY') { + event.cancel = true; + } +} +``` + +The `selectionChanging` event also drives a cascading scenario, in which the selection of one Simple Combo loads the data of the next one, for example a country, a region, and a city combo. Handle the `selectionChanging` event of each Simple Combo to load the data of the next one and to clear its selection: + +```html + + + + + + +``` + +```ts +export class SimpleComboCascadingComponent implements OnInit { + public selectedCountry: Country; + public selectedRegion: Region; + public selectedCity: City; + public countriesData: Country[]; + public regionData: Region[] = []; + public citiesData: City[] = []; + + public ngOnInit(): void { + this.countriesData = getCountries(['United States', 'Japan', 'United Kingdom']); + } + + public countryChanging(e: ISimpleComboSelectionChangingEventArgs) { + this.selectedCountry = e.newSelection as Country; + this.regionData = getCitiesByCountry([this.selectedCountry?.name]) + .map(c => ({ name: c.region, country: c.country })) + .filter((v, i, a) => a.findIndex(r => r.name === v.name) === i); + this.selectedRegion = null; + this.selectedCity = null; + this.citiesData = []; + } + + public regionChanging(e: ISimpleComboSelectionChangingEventArgs) { + this.selectedRegion = e.newSelection as Region; + this.citiesData = getCitiesByCountry([this.selectedCountry?.name]) + .filter(c => c.region === this.selectedRegion?.name); + this.selectedCity = null; + } +} +``` + +The [Grid with Cascading Combos](../../grid/cascading-combos.mdx) topic shows the same scenario in the cell editing of the Data Grid. + + + +### Filtering + +Typing in the input field of the {Platform} Single Selection Combo opens the dropdown and filters the list to the options that contain the text. The first match becomes the active option, so Enter selects it. + + + +Set `disableFiltering` to keep the whole list while users type. The `filteringOptions` object sets the key that the text filters by, and whether the filtering is case-sensitive and matches diacritics. When the text matches no option and the Combo loses the focus, the input field is cleared. + + + + + +```ts +combo.filteringOptions = { filterKey: 'name', caseSensitive: false, matchDiacritics: true }; +``` + + + + + +```tsx + +``` + + + + + +```razor + +``` + + + + + +Set to keep the whole list while users type, and to show a button in the input field that toggles case-sensitive filtering. The input sets the key that the text filters by and whether the filtering is case-sensitive, and replaces the filtering with your own. When the text matches no option and the Simple Combo loses the focus, the input field is cleared: + +```html + + +``` + +Set to let users enter a value that is not in the list. When the text matches no option, the dropdown shows an add item button, and Enter on it adds the text as a new item and selects it. The Simple Combo emits before it adds the item: + +```html + +``` + + + +### Do/Don't + +When using the Simple 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 Simple Combo is focused, you should always show it on top of the content that follows the Simple 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 {Platform} Single Selection Combo exposes the following properties. The single selection mode is a mode of the Combo, so the [Combo](./overview.mdx#properties) topic lists the complete set. See the API reference for the complete type definitions. + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `false` | Whether users select a single item and filter the list from the input field. | +| | `T[]` | `[]` | The options of the Combo. | +| | `string` | — | The field that identifies an option. | +| | `string` | — | The field that the list and the input field show. Falls back to the `valueKey`. | +| | `string` | — | The field that groups the options. | +| | `ComboValue[]` | `[]` | The selected item, as an array with one `valueKey` value or one object reference. | +| | `string` | — | The label of the Combo. | +| | `string` | — | The text that the input field shows when no item is selected. | +| | `boolean` | `false` | Whether the Combo uses the border type. | +| `open` | `boolean` | `false` | Whether the dropdown is open. | +| `disabled` | `boolean` | `false` | Whether the Combo is disabled. | +| `required` | `boolean` | `false` | Whether the Combo requires a selected item to be valid. | +| `invalid` | `boolean` | `false` | Whether the Combo shows its invalid state. | +| | `boolean` | `false` | Whether typing in the input field leaves the list unfiltered. | +| | `FilteringOptions` | — | The key that the text filters by, and whether the filtering is case-sensitive and matches diacritics. | +| | `boolean` | `false` | Whether the clear button is hidden. | +| | `T[]` | — | Read-only. The selected item as an object from the `data`, in an array with one element. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `bool` | `false` | Whether users select a single item and filter the list from the input field. | +| | `object` | — | The options of the Combo. | +| | `string` | — | The field that identifies an option. | +| | `string` | — | The field that the list and the input field show. Falls back to the `ValueKey`. | +| | `string` | — | The field that groups the options. | +| | `T[]` | — | The selected item, as an array with one element. | +| | `string` | — | The label of the Combo. | +| | `string` | — | The text that the input field shows when no item is selected. | +| | `bool` | `false` | Whether the Combo uses the border type. | +| | `bool` | `false` | Whether the dropdown is open. | +| | `bool` | `false` | Whether the Combo is disabled. | +| | `bool` | `false` | Whether the Combo requires a selected item to be valid. | +| | `bool` | `false` | Whether the Combo shows its invalid state. | +| | `bool` | `false` | Whether typing in the input field leaves the list unfiltered. | +| | `bool` | `false` | Whether the clear button is hidden. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `any[]` | — | The options of the Simple Combo. | +| | `string` | — | The field that identifies an option. | +| | `string` | — | The field that the list and the input field show. Falls back to the `valueKey`. | +| | `string` | — | The field that groups the options. | +| | `IgxInputGroupType` | `'box'` | The type of the input field: `box`, `border`, or `line`. | +| | `string` | — | The text that the input field shows when no item is selected. | +| | `boolean` | `false` | Whether the Simple Combo is disabled. | +| | `boolean` | `false` | Whether typing in the input field leaves the list unfiltered. | +| | `boolean` | `false` | Whether the input field shows the button that toggles case-sensitive filtering. | +| | `IComboFilteringOptions` | — | The key that the text filters by and whether the filtering is case-sensitive. | +| | `boolean` | `false` | Whether users can add the text of the input field as a new item. | +| | `boolean` | `false` | Whether the clear button is hidden. | +| | `number` | — | The height of the items in the list. | +| | `number` | — | The maximum height of the list. | +| | `IgxInputState` | `INITIAL` | The validation state of the Simple Combo. | +| | `any` | — | Read-only. The selected item. | +| | `any` | — | Read-only. The `valueKey` value of the selected item, or the item when there is no `valueKey`. | + + + +## Methods + +The {Platform} Single Selection Combo exposes the following methods. + + + +| Method | Description | +| --- | --- | +| | Selects the item that you pass, by its `valueKey` value or by reference, and deselects the previous one. Clears the selection when you pass nothing. | +| | Deselects the item that you pass, by its `valueKey` value or by reference. | +| `show` | Opens the dropdown. | +| `hide` | Closes the dropdown. | +| `toggle` | Opens the dropdown when it is closed, and closes it when it is open. | +| `checkValidity` | Returns whether the Combo satisfies its validation constraints. | +| `reportValidity` | Checks the validity of the Combo and shows its invalid state when it fails. | + + + + + +| Method | Description | +| --- | --- | +| | Selects the item that you pass and deselects the previous one. Clears the selection when you pass an empty array. | +| | Deselects the item that you pass. | +| | Opens the dropdown. | +| | Closes the dropdown. | +| | Opens the dropdown when it is closed, and closes it when it is open. | + + + + + +| Method | Description | +| --- | --- | +| | Selects the item that you pass and deselects the previous one. | +| | Clears the selection. | +| | Opens the dropdown. | +| | Closes the dropdown. | +| | Opens the dropdown when it is closed, and closes it when it is open. | + + + +## Events + +The {Platform} Single Selection Combo emits the following events. + + + +| Name | Description | +| --- | --- | +| `igcChange` | Emitted before the user changes the selection. The event detail holds the new value, the changed items, and the type of the change. Cancel the event to keep the selection. | +| `igcOpening` | Emitted before the user opens the dropdown. Cancelable. | +| `igcOpened` | Emitted after the dropdown opens on a user action. | +| `igcClosing` | Emitted before the user closes the dropdown. Cancelable. | +| `igcClosed` | Emitted after the dropdown closes on a user action. | + + + + + +| Name | Description | +| --- | --- | +| | Emitted with before the selection changes. Set `cancel` to keep the selection. | +| | Emitted with after the selection is committed. | +| | Emitted before the dropdown opens. Cancelable. | +| | Emitted after the dropdown opens. | +| | Emitted before the dropdown closes. Cancelable. | +| | Emitted after the dropdown closes. | +| | Emitted when the text of the input field changes. | +| | Emitted before users add a custom value to the list. | +| | Emitted when the list scrolls to options that are not loaded yet, for remote binding. | + + + +## Styling + +The Simple 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 Simple Combo Dropdown with their background and text colors. + +Change the colors of the toggle and the clear buttons of the {Platform} Single Selection 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-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 and the dropdown from the `--ig-drop-down-*` variables, so you can set all of them on the Combo. The single selection mode shows no checkboxes, so the `--ig-checkbox-*` variables have no effect. + + + +The `igc-combo` element exposes the following CSS parts in the single selection mode: + +| Part | What it styles | +| --- | --- | +| `input` | The input field. | +| `native-input` | The native input of the input field. | +| `label` | The label. | +| `prefix` | The container of the `prefix` slot. | +| `suffix` | The container of the `suffix` slot. | +| `toggle-icon` | The toggle button. `filled` is added when the Combo has a value. | +| `clear-icon` | The clear button. | +| `helper-text` | The helper text. | +| `list-wrapper` | The dropdown. | +| `header` | The container of the `header` slot. | +| `list` | The list of options. | +| `group-header` | Each group header in the list. | +| `item` | Each option in the list. `active` and `selected` are added to the active and the selected options. | +| `empty` | The container of the `empty` slot. | +| `footer` | The container of the `footer` slot. | + + + +### 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 and its dropdown, and include them with the `tokens()` mixin, which emits the matching CSS variables in the scope where you include it. + + + +```scss +@use "igniteui-angular/theming" as *; + +$custom-combo-theme: combo-theme( + $toggle-button-background: #e0e0e0 +); + +$custom-drop-down-theme: drop-down-theme( + $background-color: #e6f2ff, + $selected-item-background: #4ca7e3 +); + +:host { + @include tokens($custom-combo-theme); + @include tokens($custom-drop-down-theme); +} +``` + +The Angular Simple 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](../../overlay-styling.mdx) topic. + + + + + +The Sass functions come from the `igniteui-theming` package. See the [Theming](../../themes/overview.mdx) topic for the Sass setup. + +```scss +@use "igniteui-theming" as *; + +$custom-combo-theme: combo-theme( + $toggle-button-background: #e0e0e0 +); + +$custom-drop-down-theme: drop-down-theme( + $background-color: #e6f2ff, + $selected-item-background: #4ca7e3 +); + +:root { + @include tokens($custom-combo-theme); + @include tokens($custom-drop-down-theme); +} +``` + + + +### CSS Variables + +Set the CSS variables on a Combo or on a container when you need local styling without a Sass build step: + +```css +.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; +} +``` + + + +Use the CSS parts for other styles: + +```css +igc-combo::part(group-header) { + color: #005dcc; +} + +igc-combo::part(item selected) { + color: #000; +} +``` + + + + + + + + + + + + + + + +### Styling with Tailwind + +You can style the {Platform} Single Selection Combo using our custom Tailwind utility classes. Make sure to [set up Tailwind](../../themes/misc/tailwind-classes.mdx)[set up Tailwind](../../themes/tailwind.mdx) first. + + + +Import the Ignite UI utilities in your global stylesheet: + +```css +@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: + +```html + + ... + +``` + +The exclamation mark (`!`) gives the Tailwind utility precedence over the default theme styles of the Simple Combo. + + + + + +Set the `--ig-combo-*`, `--ig-input-group-*`, and `--ig-drop-down-*` CSS variables with Tailwind arbitrary properties: + + + + + +```html + + +``` + + + + + +```tsx + +``` + + + + + +```razor + +``` + + + + + + + + + + + + + + + +## Accessibility + +The {Platform} Single Selection Combo uses the roles of the WAI-ARIA combobox pattern: the editable input field is a `combobox` that controls a `listbox` of options, and users filter the list by typing and select an option with the keyboard. + +### Keyboard Interaction + + + +The input field of the {Platform} Single Selection Combo is a tab stop, and the focus stays in it while users type. The following keys work while the Combo has the focus: + +| Key | Action | +| --- | --- | +| Printable characters | In the input field, open the dropdown, filter the list, and activate the first match. | +| Arrow Down / Alt + Arrow Down | In the input field, opens the dropdown, moves the focus to the list, and activates the first option. In the list, activates the next option. | +| Arrow Up | In the input field, closes the dropdown. In the list, activates the previous option. From the first option, closes the dropdown and moves the focus to the input field. | +| Home / End | In the list, activates the first or the last option. | +| Space | In the list, selects the active option, or deselects it when it is selected. | +| Enter | With an active option, selects it, closes the dropdown, and moves the focus to the input field with its text selected. | +| Escape | When the dropdown is open, closes it and moves the focus to the input field. When the dropdown is closed, clears the selection. | +| Tab / Shift + Tab | When the dropdown is open, selects the active option, closes the dropdown, and moves the focus to the next or the previous focusable element. | + +A disabled Combo ignores these keys. + + + + + +The input field of the Angular Simple Combo is a tab stop, and the focus stays in it while users type. The following keys work while the Simple Combo has the focus: + +| Key | Action | +| --- | --- | +| Printable characters | In the input field, open the dropdown, filter the list, and focus the first match. | +| Arrow Down / Alt + Arrow Down | In the closed Simple Combo, opens the dropdown. In the open Simple Combo, moves the focus to the list: to the selected option, or to the first option. In the list, moves to the next option, and from the last option to the add item button when it is shown. | +| Arrow Up | In the list, moves to the previous option. From the first option, moves the focus back to the input field and selects its text. | +| Alt + Arrow Up | In the list, closes the dropdown and moves the focus to the input field. | +| Home / End | In the list, moves to the first or the last option. | +| Space | In the list, selects or deselects the focused option. | +| Enter | In the input field with a focused option that matches the text, selects it and closes the dropdown. In the list, selects the focused option, closes the dropdown, and moves the focus to the input field. On the add item button, adds the text of the input field as a new item and selects it. | +| Backspace / Delete | In the input field, clears the selection. | +| Escape | When the dropdown is open, closes it. When the dropdown is closed, clears the selection and keeps the focus on the input field. | +| Tab | When the dropdown is open, selects the focused option that matches the text, closes the dropdown, and moves the focus to the next focusable element. | + + + +### Screen Readers / ARIA + + + +The {Platform} Single Selection Combo renders the following roles and attributes: + +| Element | Role | Attributes | +| --- | --- | --- | +| The input field | `combobox` | `aria-haspopup="listbox"`, `aria-expanded`, `aria-disabled`, `aria-controls` that points to the list, and, with a helper text, `aria-describedby` that points to it | +| The `list` part | `listbox` | `aria-multiselectable="false"`, `aria-labelledby` that points to the input field, and `aria-activedescendant` that points to the active option | +| Each `item` part | `option` | `aria-selected`, `aria-posinset`, and `aria-setsize` | +| The `clear-icon` part | `button` | `aria-label` from the resource strings | + +The {Platform} Single Selection Combo also behaves as follows for assistive technology: + +- The input field takes its accessible name from the `label`. Without a label, it gets a name from the resource strings that says whether an option is selected. +- The input field is editable, and the text that users type is the filter of the list. +- The active option is announced through `aria-activedescendant` while the focus stays in the list. +- The content of the closed dropdown is `inert`. + + + + + +The Angular Simple Combo renders the following roles and attributes: + +| Element | Role | Attributes | +| --- | --- | --- | +| The input of the input field | `combobox` | `aria-haspopup="listbox"`, `aria-autocomplete="list"`, `aria-readonly="false"`, `aria-expanded`, `aria-controls` that points to the list, `aria-labelledby`, and `aria-label` | +| The dropdown | `listbox` | `aria-labelledby` that points to the `igxLabel` or to the `ariaLabelledBy` element | +| The container of the options | — | `aria-activedescendant` that points to the focused option | +| Each option | `option` | `aria-selected` | +| Each group header | `group` | — | +| The clear button | — | `aria-label` from the resource strings | +| The add item button | `button` | `aria-label` from the resource strings | + +The input field takes its accessible name from the `igxLabel` or from the input. Without them, it gets a name from the resource strings that says whether an option is selected. + + + +### Accessibility Compliance + +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../../interactivity/accessibility-compliance.mdx) topic. + +| Criterion | How the component complies | +| --- | --- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | The `combobox`, `listbox`, and `option` roles expose the structure, and the list is labeled by the `igxLabel` or the `ariaLabelledBy` elementthe input field. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | Typing filters the list, the arrow keys open the dropdown and move through the options, and Enter selects the active option. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap) | Tab closes the dropdown and moves the focus out of the Combo. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/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](#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](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast) requires. +- Show the error message in the helper text, not by color alone. See [Validation States](#validation-states). + +## Known Limitations + + + +- The single selection mode hides the search input of the dropdown, so `placeholderSearch`, `caseSensitiveIcon`, and `autofocusList` have no effect. +- The {Platform} Combo doesn't add custom values. When the text in the input field matches no option, the Combo clears the input field when it loses the focus. + + + + + +- When the Angular Simple Combo is bound to an array of primitives that contains `undefined`, the list doesn't show `undefined`. When the `valueKey` field of an object is `undefined`, the list shows the item, but users can't select it. +- When the Angular Simple Combo is bound with `ngModel` and is `required`, the `null`, `undefined`, and `''` values can't be selected. +- When the Angular Simple 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](../../layouts/virtual-scroll.mdx#known-limitations), so its limitations apply. The list renders only the options in view, and code that queries the DOM finds only those options. + + + +## API References + +The {Platform} Single Selection Combo API reference lists the complete API surface for the target platform. + + + +- + + + + + +- + + + + + +- +- +- +- + + + +## Dependencies + +The {Platform} Single Selection Combo requires a theme to apply its colors and sizes. See the framework-specific setup in [**Getting Started**](../../general/getting-started.mdx)[**Getting Started**](../../general-getting-started.mdx). + + + +The Angular Simple Combo uses the Drop Down, the Input Group, the Icon, and the Overlay. Their themes style its parts: + +- +- +- +- + + + + + +The registration of the `IgcComboComponent` also registers the input, icon, and popover elements that the Combo renders. Register the components that you place in the slots of the Combo, such as the Icon, separately. + + + + + +The Blazor Combo and the components that you place in its slots, such as the Icon, load their modules when they first render. See [Component Modules](../../general-getting-started.mdx#component-modules). + + + +## Additional Resources + +The following resources provide more {Platform} Single Selection Combo guidance and project support: + + + +- [Combo](./overview.mdx) +- [Combo Features](../../combo-features.mdx) +- [Combo Remote Binding](../../combo-remote.mdx) +- [Combo Templates](./templates.mdx) +- [Grid with Cascading Combos](../../grid/cascading-combos.mdx) + + + + + +- [Combo](./overview.mdx) +- [Combo Features](./features.mdx) +- [Combo Templates](./templates.mdx) + + + +- [Combo - Design System Component](https://www.infragistics.com/products/indigo-design/help/components/combo) +- [{ProductName} **Forums**]({ForumsLink}) +- [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +The {Platform} Single Selection Combo lets users search a list and select one option. Use these components when the selection works differently: + +- [Combo](./overview.mdx) - Use the Combo when users select more than one option. +- [Select](../../select.mdx)[Select](../select.mdx) - Use Select when users pick a single option from a short list that doesn't need search. +- [Dropdown](../../drop-down.mdx)[Dropdown](../dropdown.mdx) - Use Dropdown to show a list of actions or options from a button or another element. + +## FAQ + +These questions cover common {Platform} Single Selection Combo setup, selection, and usage scenarios. + + + + Use the Angular Simple Combo, the `igx-simple-combo` component, instead of the Combo. The Simple Combo selects one item and lets users type in its input field to filter the list.Set `singleSelect` on the {Platform} Combo. The Combo then selects one item at a time, lets users type in its input field to filter the list, and hides the search input and the checkboxes of the dropdown. + + + Bind the Angular Simple Combo with `[(ngModel)]` or a form control to a single `valueKey` value, or call the `select` method with the item. Without a `valueKey`, the Simple Combo uses a reference to the object in its `data`.Set the `value` of the {Platform} Combo to an array with the `valueKey` value of the item, or call the `select` method with the item. Without a `valueKey`, the {Platform} Combo uses a reference to the object in its `data`. + + + Yes. Set `allowCustomValues` on the Angular Simple Combo, and the dropdown shows an add item button when the text matches no option. The Simple Combo adds the text as a new item and selects it.No. The {Platform} Combo selects options from its `data` only. When the text in the input field matches no option, the Combo clears the input field when it loses the focus. + + + The Angular Simple Combo filters by the `displayKey` field. Check that `disableFiltering` is not set, and that `filteringOptions` or `filterFunction` match the field that the list shows.The {Platform} Combo filters by the `displayKey` field, or by the `filterKey` of its `filteringOptions`. Check that `disableFiltering` is not set, and that the key names a field of the options. + + + Use the {Platform} Single Selection Combo when the list is long and users need to search it by typing. Use the {Platform} Select for a short list from which users pick an option without searching. + + diff --git a/docs/xplat/src/content/en/components/inputs/combo/templates.mdx b/docs/xplat/src/content/en/components/inputs/combo/templates.mdx index 0f62656b41..f9d373a207 100644 --- a/docs/xplat/src/content/en/components/inputs/combo/templates.mdx +++ b/docs/xplat/src/content/en/components/inputs/combo/templates.mdx @@ -1,349 +1,706 @@ --- -title: "{Platform} ComboBox Component Templates – {ProductName}" -description: "{ProductName} ComboBox component templates" -keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} ComboBox Component Templates" +title: "{Platform} Combo Templates" +description: "The {ProductName} Combo Templates replace the default content of the Combo areas: the items, the group headers, the header and the footer of the list, the empty list, the toggle and the clear icons, and the input field." +keywords: "{Platform} Combo Templates, {ProductName}, combo item template, combo group header template, combo header template, combo footer template, combo empty template, combo toggle icon, combo clear icon, templated combo input" license: MIT -mentionedTypes: ["Combo"] +last_updated: "2026-11-09" +mentionedTypes: ["Combo", "ComboItem", "ComboHeader", "ComboList"] llms: - description: "The {ProductName} ComboBox component allows defining custom templates for different areas such as items, group headers, empty list, and icons." + description: "The {ProductName} Combo Templates replace the default content of the Combo areas: the items, the group headers, the header and the footer of the list, the empty list, the toggle and the clear icons, and the input field." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Combo Templates -# {Platform} ComboBox Templates +The {ProductName} Combo Templates replace the default content of the Combo areas: the items, the group headers, the header and the footer of the list, the empty list, the toggle and the clear icons, and the input field. -The {ProductName} ComboBox component allows defining custom templates for different areas such as items, group headers, empty list, and icons. + -## ComboBox Templates Example +The Angular Combo takes each template as an `ng-template` element with one of its template directives, placed inside the `igx-combo` element. The directives come with the `IGX_COMBO_DIRECTIVES` token, as the [Combo](./overview.mdx#getting-started) topic shows, together with the `igxLabel`, `igx-prefix`, `igx-suffix`, and `igx-hint` elements that template the input field. - + + + + +The {Platform} Combo renders its items and group headers through the and properties, and takes the content of the other areas through its slots. Use a `` for simple text or symbols, and an [Icon](../../layouts/icon.mdx) for icons. The `header` and `footer` slots also accept the `
` and `