IgxCombo (Component)

Combo Specification

Owned by

PwnJS

Developer Name

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date:

Signed off by

Konstantin Dinev | Date:
Architect | Date:

Revision History

Version	User	Date	Notes
0.1	Viktor Slavov	May 8, 2018	Initial Draft
0.2	Plamena Miteva	May 10, 2018	Test Scenarios
0.3	Nikolay Alipiev	May 11, 2018	Features and API
0.4	Nikolay Alipiev	May 11, 2018	Features and API after first review
0.5	Nikolay Alipiev	June 6, 2018	Features and API Update
0.6	Nikolay Alipiev	June 20, 2018	Features and API Update
0.7	Plamena Miteva	June 20, 2018	Test Scenarios Update
1.1	Viktor Slavov	Jan 18, 2019	Add input group templating
1.2	Danail Marinov	Jun 10, 2019	Display Density designs added
1.3	Viktor Slavov	Jun 18, 2019	Added display density + itemHeight example
1.4	Viktor Slavov	Jul 19, 2019	Add overlay settings + fix typo
1.5	Stefan Ivanov	June 1, 2020	Add user story for ellipsis
1.6	Ivaylo Ganchev	Jul 1, 2020	Add default position strategy in use
1.7	Plamena Miteva	Jul 19, 2020	Add case sensitive search feature
1.8	Radoslav Mirchev	Oct 19, 2021	Template Update
1.9	Plamena Miteva	July 08, 2022	API Update
1.10	Nikolay Alipiev	June 07, 2023	API Updates - change what `value` and `selection` are doing. Introduce `displayValue`
1.11	Nikolay Alipiev	Nov 17, 2023	API Updates. Changes - PRs: 1, 2, 3, 4

1. Overview

Objectives

The igx-combo provides a powerful input, combining features of the basic HTML input, select and the IgniteUI for Angular igx-drop-down controls

2. User Stories

As an end user, I want to:

have an input that allows me to select a single item from a dropdown menu
have an input that allows me to select multiple items from a dropdown menu:
- where each item marked as selected has a distinct visual
- where each item marked as selected has a distinct visual style as well as a checkbox
have an input that allows me to type in a value if I cannot find it in the listed options
to be able to easily empty the input after I have selected an item
to be able to easily empty the input after I have selected multiple items
have my browser quickly load lots of list items
be able to easily and quickly navigate through the list of items
be able to start typing in the input and have the suggested options filtered accordingly
be able to change the search case sensitivity
be able to have the suggestions dropdown pop up by using my keyboard
be able to select and confirm one option from the dropdown by using my keyboard
be able to select and confirm multiple options from the dropdown by using my keyboard
be able to clear any selected options from the dropdown by using my keyboard
be able to close the dropdown without selecting anything
be able to close the dropdown without selecting anything by using my keyboard
to cut the item content/text and add ... so that it fits the available width when it is too long (ellipsis).

Developer Stories

As a developer, I want to

get/set the selection type of the input (single/multiple) - only multiple selection mode with checkboxes
get/set whether the field is required (required: true/false)
get/set the value(s) that are selected (single/multiple/clear)
get/set the editing state of the input (read-only: true/false)
bind the control to an array of primitive values
bind the control to an array of objects and:
- be able to specify which property should be used for the text value
- be able to specify which property should be used for the value
bind the control to a remote set of data
select falsy values, i.e., 0, false, '', null, NaN
specify a template for the way data should be visualized inside the dropdown
specify a template for (or straight up remove) the icon for the combo's "clear" button
specify a template for (or straight up remove) the icon for the combo's "toggle" button
template the combo's read-only input like I would a standard input-group, using igx-prefix, igx-suffix and igx-label
alter the data to which the control is bound during runtime
filter the data of the dropdown during runtime
be notified, when the value of the input has changed
be notified, when the dropdown of the input is shown
be notified, when the user fires keyboard events inside of the input's dropdown
be able to set Comfortable, Cosy or Compact Display Density
be able to override the Display Density item height via the itemHeight @Input
be able to override the Combo's default OverlaySettings, configuring how the items drop down is shown

Comfortable, Cozy and Compact Display density

3. Test Scenarios

Automation

Combo's input text box is read-only and user is not able to type in
Combo's input text box can be customized with elements of a standard igx-input-group (e.g. label, prefix, suffix)
Dropdown menu popup gets displayed when
- dropdown button is pressed
- down arrow key is pressed
- down arrow + ALT keys are pressed
When opened the dropdown popup can be closed by pressing
- the dropdown button
- up arrow key
- up arrow + ALT keys
The dropdown can be closed without selecting anything
Search input is focused when dropdown is opened
onOpening/onClosing event is fired on opening/closing the dropdown list
onOpened/onClosed event is fired after the dropdown list has been opened/closed
Pressing Home key scrolls up to the first item of the dropdown list
Pressing End key scrolls down to the last item of the dropdown list
Vertical scrollbar is visible only when the items does not fit inside the dropdown container
Dropdown list appearance can be customized by applying templates
When grouping is enabled, the dropdown displays correctly all group headers and their sub items
When no results are filtered for a group, the group header should not be visible
Add button is visible when typing in the search input.
Combo list gets filtered on every stroke while typing in the textbox
Clearing the filter textbox restores the initial combo dropdown list
Typing a value that matches an already selected item should remove the add item button
When no results are filtered, the 'SelectAll' checkbox should not be visible
Escape key should clear the search input text and close the dropdown list
onSearchInput event is triggered on every user modification of the input value
All selected items are appended to the input textbox separated by comma in the order they have been selected
Deselected item is removed from the input textbox without changing the order of the rest of the appended items
A dropdown list item can be selected by
- navigating with the up and down keys and pressing space key
- checking its check box
User can deselect an item by unchecking the item's check box
The SelectAll option selects/deselects all dropdown list items when checked/unchecked
When items are grouped user is able to select only list items, not the group headers
When using key navigation to move up and down the items list the current item is focused and movement starts from the last selected item if any or from the first item in the list if no list item is selected
onSelectionChange event is triggered when an item is being selected or deselected
Selected items and their checkboxes are highlighted in the dropdown list
Selecting an item using the ‘selectItems’ method will add the item to the selected collection or will override the selection according to its second parameter
Combo can be bound to an array of primitive data, array of objects or remote service
In case combo's data source has not been bound to any data, an empty template is rendered.
The component's data source can be changed at run-time
Combo applies all appropriate classes on initialization, on item focusing, selection and filtering.

Manual

Browser loads the combo dropdown list with a big number of items in a timely manner
Scrolling the combo dropdown list with a big number of items is fast

4. Functionality

4.1. End User Experience

Users are provided with an input field that has a dropdown with possible values. The user can open the dropdown using the keyboard or by clicking the dropdown button or the textbox itself. The user can choose a value from the dropdown (using either mouse or keyboard). The user can type into the filtering input and the dropdown will display only the appropriate matching values. The user can change the search case-sensitivity. Depending on the setup of the control, the user can also enter custom values. The user can select a single value or multiple values. Values can be cleared.

List items container positioning:

version(v10.1.0)

The component uses AutoPositionStrategy as a default position strategy and should refer to it for more details. In short: If there is enough space in the viewport below the combo's input group, the items list container will be positioned below the input group. If there is not enough space in the viewport below the combo's input group, the items list container will flip above the input group. If after flipping direction the content goes out of the viewport, auto strategy will revert to initial start point and direction and will push the content into the viewport. Note after pushing the content it may hide the combo's input.

4.2. Developer Experience

Adding a combo-box:

<igx-combo #myCombo [data]="localData"></igx-combo>

4.3 Features

Data Binding
- Local Data
- Remote Data
Value Binding
Custom Value
Allow Adding Custom Value
Virtual Drop Down Items
Multiple Selection with checkboxes (the only state)
- Selected items are separated with comma
- Selected items cannot be edited
- Selected items can be deselected only from checkboxes
- The search input is placed at the top of the drop down
- Select All at the top of all items
Filtering
Grouping
Templates - item, header, footer, group, empty, add new item, action failure
Cascading Combos
Forms support - Template Driven and Reactive Forms

4.4. Keyboard Interaction

Navigate through open drop down items - Arrow Up, Arrow Down, Home, End
Select an item - Space
Open/Close Drop Down - Arrow Up, Arrow Down, Esc, Enter

5.5 API

Properties

IgxComboComponent

Name	Description	Type
`id`	combo id	string
`data`	combo data source	any[]
`allowCustomValue`	enables/disables combo custom value	boolean
`filterable`	enables/disables combo drop down filtering - enabled by default	boolean
`showSearchCaseIcon`	defines whether the search case-sensitive icon should be displayed - disabled by default	boolean
`valueKey`	combo value data source property	string
`displayKey`	combo display data source property	string
`groupKey`	combo item group	string
`virtualizationState`	defines the current state of the virtualized data. It contains `startIndex` and `chunkSize`	`IForOfState`
`totalItemCount`	total count of the virtual data items, when using remote service	number
`width`	defines combo width	string
`displayDensity`	defines the display density of the combo . Available options are `cosy`, `compact`, `comfortable`	`DisplayDensity
`itemsMaxHeight`	defines drop down maximum height	number
`itemsWidth`	defines drop down width	string
`itemHeight`	defines drop down item height	number
`placeholder`	defines the "empty value" text	string
`searchPlaceholder`	defines the placeholder text for search input	string
`collapsed`	gets drop down state	boolean
`disabled`	defines whether the control is active or not	boolean
`ariaLabelledBy`	defines label ID related to combo	boolean
`type`	Combo style. - "line", "box", "border", "search"	string
`valid`	gets if control is valid, when used in a form	boolean
`overlaySettings`	gets/sets the custom overlay settings that control how the drop-down list displays	OverlaySettings
`autoFocusSearch`	controls whether the search input should be focused when the combo is opened	boolean
`filteringOptions`	Configures the way combo items will be filtered	IComboFilteringOptions
`filterFunction`	Gets/Sets the custom filtering function of the combo	`(collection: any[], searchValue: any, caseSensitive: boolean) => any[]`

Getters

Name	Description	Type
`displayValue`	the value of the combo text field	string
`value`	the value of the combo	any[]
`selection`	the selected items of the combo	any[]

Note: the combo items inside of the combo drop-down to have a minimum height of 2 rem

Methods

Name	Description	Return type	Parameters
`open`	Opens drop down	`void`	`None`
`close`	Closes drop down	`void`	`None`
`toggle`	Toggles drop down	`void`	`None`
`selectedItems`	Get current selection state	`any[]`	`None`
`select`	Select defined items	`void`	items: `any[]`, clearCurrentSelection: `boolean`
`deselect`	Deselect defined items	`void`	items: `any[]`
`selectAllItems`	Select all (filtered) items	`void`	ignoreFilter?: `boolean` - if `true` selects all values
`deselectAllItems`	Deselect (filtered) all items	`void`	ignoreFilter?: `boolean` - if `true` deselects all values
`selected`	Toggles (select/deselect) an item by key	`void`	itemID: any, select = true, event?: Event

Events

Name	Description	Cancelable	Emitted with
`selectionChanging`	Emitted when item selection is changing, before the selection completes	true	`IComboSelectionChangingEventArgs`
`searchInputUpdate`	Emitted when an the search input's input event is triggered	true	`IComboSearchInputEventArgs`
`addition`	Emitted when an item is being added to the data collection	true	`IComboItemAdditionEvent`
`dataPreLoad`	Emitted when new chunk of data is loaded from the virtualization	false	`IForOfState`
`opening`	Emitted before the dropdown is opened	false	`IBaseCancelableBrowserEventArgs`
`opened`	Emitted after the dropdown is opened	false	`IBaseEventArgs`
`closing`	Emitted before the dropdown is closed	false	`IBaseCancelableBrowserEventArgs`
`closed`	Emitted after the dropdown is closed	false	`IBaseEventArgs`

5. ARIA Support

The following components gets the corresponding aria attributes:

The aria-labelledby attribute is applied to both combo input and dropdown and can be set by the ariaLabelledBy property, the combo label or placeholder.

The dropdown item container has aria-activedescendant attribute to identify the currently active element of the item list and the items inside it have role role="option" or role="group" in case they are header items.

6. Assumptions and Limitations

When using the display density input or providing it through Angular's DI:

if no itemHeight input is provided OR is set to null, the combo with adhere to the Display Density's standard
if itemHeight input is provided, only the combo input with adhere to the Display Density's standard. Items will have the specified in itemHeight height Following the Material Design Guidelines the following setting were omitted, to allow easy configuration of the feature:
Drop down items inside of the combo have a minimum height of 2 rem

Due to limitations imposed by different browsers, be aware of the following:

In Firefox and IE, the combo input displays a cursor even though input is disabled
Hitting the Backspace key while on a disabled input in IE functions as the browser's Back navigation button

When setting falsy values in the combo data, be aware of the following:

Primitive data:
- if 'undefined' is added to the array of data, e.g. data = [0, false, '', NaN, null, undefined], it will not be displayed in the dropdown and will not be present in the combo data
Array of objects:
- if the value of the value property, i.e. valueKey, is undefined, the item will be displayed in the dropdown, but cannot be selected

When the combo is bound to a remote service and there is a predefined selection, be aware of the following: