-
Notifications
You must be signed in to change notification settings - Fork 162
IgxCombo (Component)
- Overview
- User Stories
- Test Scenarios
- Functionality
- ARIA support
- Assumptions and Limitations
- References
PwnJS
Developer Name
Stefan Ivanov
- Peer Developer Name | Date:
- Stefan Ivanov | Date:
- Konstantin Dinev | Date:
- Architect | Date:
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.12 | Radoslav Karaivanov | Jan 9, 2024 | Added groping section |
1.13 | Radoslav Karaivanov | Jan 10, 2024 | Dropped items sort when grouping |
The igx-combo
provides a powerful input, combining features of the basic HTML input
, select
and the IgniteUI for Angular igx-drop-down
controls
- 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).
- 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
andigx-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
- 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.
- 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.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, the label, 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
- When a group key is set, the combo will group its items based on that key.
- Items which cannot be resolved based on the passed group key (that is
T[groupKey]
returningnull
orundefined
) will be aggregated into a group named "Other". - When grouping is enabled, developers may control the sorting directions of the groups through the
groupSortingDirection
property. Defaults toSortingDirection.Asc
(ascending). - The sorting is locale aware.
-
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
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 | string
|
| 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[]
|
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
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 |
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 |
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.
When using the display density input or providing it through Angular's DI:
-
if no
itemHeight
input is provided OR is set tonull
, 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 initemHeight
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
- if 'undefined' is added to the array of data, e.g.
- Array of objects:
- if the value of the value property, i.e.
valueKey
, isundefined
, the item will be displayed in the dropdown, but cannot be selected
- if the value of the value property, i.e.
When the combo is bound to a remote service and there is a predefined selection, be aware of the following:
- the input of the combo will remain blank until the requested data is not loaded.