DropDown Specification

Revision History

Version	User	Date	Notes
0.1	Alexander Marinov	April 20, 2018	Initial Draft
0.2	Milko Venkov	April 25, 2018	Add changes to API
0.3	Alexander Marinov	May 3, 2018	Add changes to API
0.4	Alexander Marinov	May 9, 2018	Update API and test scenarios
0.5	Milko Venkov	May 10, 2018	Updating the API
0.6	Milko Venkov	May 15, 2018	Updating the API
0.7	Milko Venkov	July 5, 2018	Updating specification
0.8	Milko Venkov	July 24, 2018	Add isSelected setter to igxDropDownItem
1.1	Viktor Slavov	Jan 25, 2019	Add IgxDropDownGroup section, user stories
1.2	Milko Venkov	Feb 15, 2019	Assumptions and Limitations update - modal
1.3	Danail Marinov	Jun 10, 2019	Display Density variations
1.4	Ivaylo Ganchev	Feb 18, 2020	Update default `mix-width` and `max-width`
1.5	Stefan Ivanov	June 1, 2020	Add story for content ellipsis
1.6	Plamena Miteva	July 8, 2022	Updating the API

1. Overview

Objectives

The igx-dropdown should display a list of items and should support selection of a single item.

The igx-dropdown should display a scrollable list of items which may be visually grouped. Clicking or tapping an item should select the item and should close the drop down.

The igx-dropdown should appear above all other in-app UI elements.

2. User Stories

As an end user, I want

to see a dropdown list of available choices
to have a selection made by default
not to have a selected item by default
to select a choice using a mouse click
to select a choice using the SPACE and ENTER keys
to see the dropdown above all other elements on the page
to scroll the list of choices if they are too many
to be able to scroll navigate through the items using Up/Down arrow keys and Home/End keys.
to see the choices grouped if applicable
to close the dropdown by selecting an item or by pressing the ESC key
the dropdown to preserve selection
to have visual clue if a choice from the list is not selectable
to have visual clue if a choice from the list is selected, focused or hovered.
to change the selected values indefinitely, so that I can change my choice.
to have or not animations on dropdown open, so that I have a meaningful interactions.
to have dropdown opening positions that are meaningful and dependent on my needs.
to have separators in the dropdown list, so that I have the items organized depending on my needs.
when the item content/text is too long to cut it and add ... to fit the available width (ellipsis).

Developer Stories

As a developer, I want to

select an item
be notified, when selection has changed
be able to implement the dropdown to any kind of anchor.
open the dropdown within the viewport.
set the width of the dropdown.
set the height, and if it is exceeded a vertical scroll should appear.
be able to select from different animations or disable all animation for the dropdown opening/closing, so that the interaction is meaningful.
default opening positions (Top start, Top end, Bottom start, Bottom end, attempt to vertically align the currently selected anchor with the list item.)
be able to customize the opening position by anchor margins (Top, Bottom, Left, Right) in pixels.
add a separator in the dropdown items so that I can organize them better.
be able to group hierarchical data in groups without the need to flatten it
to be able to set Comfortable, Cosy or Compact Display Density

3. Functionality

3.1. End User Experience

Users are able to select an item from a predefined list of items which is displayed in the application UI.

3.2. Developer Experience

Developers are able to select items programatically like:

igxDropDown.setSelectedItem(2);

Developers can also subscribe to an event emitted before the item selection is completed:

<igx-dropdown #dropdown (onSelection)="itemSelection($event)"></igx-dropdown>

The igx-drop-down-item-group component can be used inside of the igx-drop-down to group igx-drop-down-items. The example below illustrates how to display hierarchical data in drop down groups:

    // in example.component.ts
    export class MyExampleComponent {
        ...
        foods: any[] =  [{
            name: 'Vegetables',
            entries: [{
                    name: 'Cucumber',
                    refNo: `00000` 
                }, {
                    name: 'Lettuce',
                    refNo: `00001`
                },
                ...
            ]   
        }, {
            name: 'Fruits',
            entries: [{
                    name: 'Banana',
                    refNo: `10000` 
                }, {
                    name: 'Tomato',
                    refNo: `10001`
                },
                ...
            ]   
        }];
    }

    <!-- in example.component.html -->
    <igx-drop-down>
        <igx-drop-down-item-group *ngFor="let foodGroup of foods" [label]="foodGroup.name">
            <igx-drop-down-item *ngFor="let food of foodGroup.entries" [value]='food.refNo'>
                {{ food.name }}
            </igx-drop-down-item>
        </igx-drop-down-item-group>
    </igx-drop-down>

3.3. Keyboard Navigation

The default way to select an item from the dropdown is by mouse click. To enable keyboard navigation IgxDropDownItemNavigationDirective should be added. If keyboard navigation is enabled, selection is also possible using the ENTER and SPACE keys. Pressing UP and DOWN keys is changing the focus to the previous/next item but is not changing the selection. Pressing ENTER or SPACE key is closing the dropdown after the selection is changed.

Pressing the Esc key is closing the dropdown and is not changing the selection.

Pressing the Home key is scrolling the list and set the focus to the first item which is not disabled or header.

Pressing the End key is scrolling the list and set the focus to the last item which is not disabled or header.

3.4. User Interface

DropDown can be configured for Comfortable, Cosy and Compact Display Density with the following settings:

Comfortable Display Density is recommended for mobile.

Cosy and Compact Display Density are recommended for desktop.

Тext does not wrap.

4.5. API

Properties

IgxDropDownComponent

Name	Description	Type
selectedItem	Gets the selected item	IgxDropDownItemComponent
items	Gets all non-header items	IgxDropDownItemComponent[]
headers	Gets all header items	IgxDropDownItemComponent[]
allowItemsFocus	Allows items to take focus	boolean
width	Sets/gets the tab width of the control	string
height	Sets/gets the tab height of the control	string
id	Sets/gets the dropdown's id	string
element	Get dropdown html element	HtmlElement
collapsed	Gets if the dropdown is collapsed	bool
labelledby	Sets aria-labelledby attribute	string

IgxDropDownItemComponent

Name	Description	Type
isSelected	Sets/Gets if the item is the currently selected one in the dropdown	boolean
disabled	Sets/gets if the given item is disabled	boolean
isFocused	Sets/gets if the given item is focused	boolean
isHeader	Sets/gets if the given item is header	boolean
index	Gets item index	number
elementHeight	Gets item element height	number
element	Get item html element	ElementRef

Note: igx-dropdown-item API isSelected setter will not trigger the onSelection event Note: if an igx-drop-down-item is inside of a disabled igx-drop-down-item-group, the disabled get will always return true

IgxDropDownGroupComponent

Name	Description	Type
disabled	Sets/gets if the given item group is disabled. When true, disables all drop down items inside of the group	boolean
label	The label of the group. Blank by default	string

Methods

IgxDropDownComponent

Name	Description	Parameters
toggle	Toggles the dropdown	overlaySettings?
open	Opens the dropdown	overlaySettings?
close	Closes the dropdown	none
setSelectedItem	Select an item by index	new selected item index

Events

IgxDropDownComponent

Name	Description	Cancelable	Parameters
onSelection	Emitted when item selection is changing, before the selection completes	false	{ISelectionEventArgs}
onOpening	Emitted before the dropdown is opened	true	IBaseCancelableBrowserEventArgs
onOpened	Emitted after the dropdown is opened	false
onClosing	Emitted before the dropdown is closed	true	IBaseCancelableBrowserEventArgs
onClosed	Emitted after the dropdown is closed	false

Note: igx-dropdown API setSelectedItem method will trigger the onSelection event

5. ARIA Support

We provide the aria-selected property which lets the screen readers know if an item is selected or not.

The following components gets the corresponding aria attributes

selected item - aria-selected=true (https://www.w3.org/TR/wai-aria-1.1/#aria-selected)

6. Assumptions and Limitations

the only mode of selection will be single

multiple selection is out of scope for the dropdown component and will be provided by another component.

moving the focus up and down via the keyboard will not change selection.
Pressing the Esc key will close the dropdown, but will not update the selection.
Dropdown will not handle page up and page down key actions.
By default Dropdown will not close on click outside and will be shown as modal and centered on the screen. To show dropdown as not modal and with close on outside click the developer may add IgxToggleAction directive to the caller of the dropdown, or provide OverlaySettings with modal set to false and closeOnOutsideClick set to true to the open/toggle method.
We will provide default value for min-width with CSS and will allow the users to set actual width property. There will not be a default max-width set, as it may differ per app-scenario.
The igx-drop-down-item-group tag should be used only to group igx-drop-down-items. All other content will be disregarded by the IgxDropDownGroupComponent