Combobox

1<!--example input with datalist-->
2<label for="ice-cream-choice">Choose an ice-cream flavor:</label>
3<input
4        id="ice-cream-choice"
5        list="ice-cream-flavors"
6        name="ice-cream-choice"
7        type="text">
8<datalist id="ice-cream-flavors">
9    <option>Butter Pecan</option>
10    <option>Chocolate</option>
11    <option>Cookies and Cream</option>
12    <option>Strawberry</option>
13    <option>Tutti Frutti</option>
14    <option>Vanilla</option>
15</datalist>

No ARIA attributes need or should be applied for this native HTML combobox to be accessible to screen reader users. When encountered, screen readers announce the input as an editable combobox with a popup with suggestions and announce its current state and location as it is operated.

The native HTML combobox constructed with input and datalist elements present a touch interface in mobile iOS and Android browsers that, in most cases, replicate expected behavior for both keyboard and pointer device users. A sustained touch sets focus and fires a pointerdown event, then a pointerup event when touch is removed. A quick tap is needed to fire a click event.

A significant difference in behaviour between mobile and desktop browsers that may be difficult to achieve with a custom combobox is the manner in which options are presented. When the text field receives focus on a mobile device, the options may appear as a set of buttons at the top of the touch interface keyboard rather than in a listbox popup.

1<label for="favorite-pet">Your favorite pet</label>
2<select id="favorite-pet" name="pets">
3    <option value="">--Please select--</option>
4    <option>Dog</option>
5    <option>Cat</option>
6    <option>Chinchilla</option>
7    <option>Hamster</option>
8    <option>Parrot</option>
9    <option>Spider</option>
10</select>

ARIA attributes inform screen reader users what they’ve come across and how to use it. While browsers provide that with the native HTML combobox, they need to be explicitly set for a custom combobox.

• The input field has an accessibility name derived from its label.
• The input field has ARIA attributes:
  • role is set to combobox.
  • aria-autocomplete property is set to list to indicate its autocomplete behavior.
  • aria-controls property references the ID of the role=listbox element.
  • aria-haspopup property is set to the role, listbox, of its popup.
  • aria-expanded state is set to true when the popup is open and false when collapsed.
  • aria-activedescendent property is dynamically set to the ID of the option that has been highlighted by user arrow-key navigation.
• The ul listbox has ARIA attributes:
  • role is set to listbox.
  • aria-labelledby is set to the ID of the input label, providing it with an accessibility name.
• The li elements have ARIA attributes:
  • role is set to option.
  • aria-selected is dynamically set to true when an option is selected and false otherwise.

1<!-- Combobox HTML with an active option -->
2<label id="cbxLabel" for="cbxInput">
3    Choose an ice cream flavor:
4</label>
5<div class="combobox-wrapper">
6    <div class="input-wrapper">
7        <input
8                id="cbxInput"
9                type="text"
10                name="ice-cream-choice"
11                role="combobox"
12                autocomplete="off"
13                aria-autocomplete="list"
14                aria-controls="cbxListbox"
15                aria-haspopup="listbox"
16                aria-expanded="true"
17                aria-activedescendant="cbxOption1"
18                value="c"
19        />
20        <span class="dropdown-icon" role="presentation">▼</span>
21    </div>
22    <ul
23            id="cbxListbox"
24            class="open"
25            role="listbox"
26            aria-labelledby="cbxLabel">
27        <li id="cbxOption0" role="option" aria-selected="false">
28            Butter Pecan
29        </li>
30        <li id="cbxOption1" role="option" aria-selected="false" class="active">
31            Chocolate
32        </li>
33        <li id="cbxOption2" role="option" aria-selected="false">
34            Cookies and Cream
35        </li>
36    </ul>
37</div>

Notes:

• The input element has autocomplete=off to prevent some browsers from popping up a separate listbox with previously typed entries as additional suggestions. (Intended to be helpful, but not so much in this case.)
• The dropdown icon is simply a visual affordance here rather than a button. Clicking or tapping on the input field itself opens the popup.

1<!--Selecting an option value closes the popup and sets the combobox value.-->
2<label id="cbxLabel" for="cbxInput">
3    Choose an ice cream flavor:
4</label>
5<div class="combobox-wrapper">
6    <div class="input-wrapper">
7        <input
8                id="cbxInput"
9                type="text"
10                name="ice-cream-choice"
11                role="combobox"
12                autocomplete="off"
13                aria-autocomplete="list"
14                aria-controls="cbxListbox"
15                aria-haspopup="listbox"
16                aria-expanded="false"
17                value="Chocolate"
18        />
19        <span class="dropdown-icon" role="presentation">▼</span>
20    </div>
21    <ul
22            id="cbxListbox"
23            role="listbox"
24            aria-labelledby="cbxLabel">
25        <li id="cbxOption1" role="option" aria-selected="true">
26            Chocolate
27        </li>
28    </ul>
29</div>

While most of these CSS rules implement styling choices, a few play a role in the function and accessibility of the combobox:

• Focus and hover visibility provided with :focus and :hover pseudo classes
• Popup display provided with [role=listbox].open
• Option navigation visibility provided with [role=option].active

1.combobox-wrapper {
2
3    position: relative;
4    max-width: 320px;
5
6    .input-wrapper {
7        position: relative;
8        display: flex;
9        align-items: center;
10        max-width: 320px;
11    }
12
13    input {
14        display: block;
15        width: 100%;
16        padding: 8px 48px 8px 12px;
17        outline: 1px solid gray;
18        outline-offset: -1px;
19        border-radius: 4px;
20        background: #fff;
21    }
22
23    input + .dropdown-icon {
24        display: none;
25        position: absolute;
26        right: 0.5em;
27        pointer-events: none;
28    }
29
30    input:focus {
31        outline: 2px solid royalblue;
32        outline-offset: -2px;
33    }
34
35    input:focus + .dropdown-icon,
36    input:hover + .dropdown-icon {
37        display: block;
38    }
39
40    ul[role=listbox] {
41        position: absolute;
42        display: none;
43        width: 100%;
44        max-width: 320px;
45        margin-top: 2px;
46        padding: 8px 4px;
47        background: white;
48        border: 1px solid gray;
49        border-radius: 4px;
50        z-index: 10;
51        list-style: none;
52    }
53
54    ul[role=listbox].open {
55        display: block;
56    }
57
58    [role=option] {
59        width: 100%;
60        font-size: 16px;
61        line-height: 2;
62        padding: 4px 8px;
63        border-radius: 4px;
64    }
65
66    [role=option].active,
67    [role=option]:hover {
68        background: lightcyan;
69        outline: solid 1px royalblue;
70    }
71}

Because interaction can be implemented using JavaScript with a variety of methods and frameworks, here we simply outline what should occur.

When users interact with this combobox, its HTML structure and attributes changes in the following ways:

This combobox has list aria-autocomplete behavior. When there is an entry in the input field, only those options that contain the entry string (independent of case) are included in the listbox popup. In our example, the letter “c” in the input field filters the options to “Butter Pecan,” “C hocolate,” and “Cookies and Cream.” With no entry, all options are displayed. With no match, no popup.

HTML structures that convey information through presentation have a semantic role that must be conveyed to assistive technologies. Role is automatic for a native HTML combobox, such as input element referencing a datalist element, but the ARIA role attribute must be explicitly set for all semantic elements of a custom combobox.

• The combobox input element has role set to combobox.
• The popup widget has role set to listbox, grid, tree or dialog.
• The semantic elements of the popup composite have role set according to its structure:
  • Each navigable item in a listbox has role="option".
  • Each navigable item in a grid has role set to gridcell, rowheader, or columnheader according to its structure.
  • Each navigable item in a tree has role set to treeitem.
  • Navigation in a dialog popup is according to its embedded tab sequence with each item having a role according to its function.

Every element of a combobox widget that has a semantic role should also have an accessible name so that screen reader users are aware of which such element they are on, information they cannot get from its visual context.

Each semantic element should have a unique label:

• The combobox input element
• Each of the navigable components of the popup composite.
• The popup composite itself

The label can be provided in a number of ways, detailed in the following WCAG Techniques:

• Using HTML form controls and links
• Use label elements to associate text labels with form controls
• Use aria-labelledby to provide a name for user interface controls
• Use aria-label to provide an invisible label where a visible label cannot be used

A combobox is a kind of input, a form control, that must have name and value properties that can be submitted with a form that owns it. For that purpose, the combobox input element must be one of the following:

• An input element with name and value attributes or properties. (The input element should not have the multiple attribute when used as a combobox.)
• A button element with name and value attributes or properties.
• A select element with name attribute and value property set from selected, owned option element.
• a form-associated custom element

Note that setting an accessibility label for the combobox does not set its name property. They have separate purposes and usually have separate values.

The combobox aria-controls property must identify the ID of the popup element so that browsers and assistive technologies are aware of the relationship.

Note: An input element with a list attribute referencing a datalist element provides this relationship.

The combobox aria-haspopup property must correctly identify the role of its associated popup so that users are aware of its nature. If set, it must have one of the following values and must correspond to the popup role:

With a custom combobox, screen readers inform their users of the availability of the popup according to the value of the aria-expanded attribute of the combobox input element. (No default value.)

When keyboard users navigate the listbox, grid, or tree popup associated with a combobox, keyboard focus remains on the combobox itself, while an interactive element within the popup become “active” when a user navigates to it. The active element is then the object of keyboard action on the combobox input, either handled by custom JavaScript in a custom combobox or by the browser in a native HTML combobox.

So that users are aware when a popup element is active, a custom combobox must:

• Set aria-activedescendant on the combobox input element to the ID of the active element so that screen readers are aware of which element is active. ( Note: Setting this attribute will not make the element active — that must be handed in code.)
• Set a visual focus indicator on the active element in addition to the visual focus indicator on the input element itself.

A selectable popup element (with role option, gridcell or treeitem) should set aria-selected to convey its selected state to assistive technologies.

An option, gridcell, or treeitem selectable element is selected when the combobox input has its value. This differs from the behavior when a listbox, grid, or tree is directly in the tab sequence, where selection occurs when a selectable item receives visual focus.

Do not set aria-checked. Though these roles also support aria-checked, its purpose is for multiselect applications and should not be set in a combobox widget.

Set aria-autocomplete property on the input element to inform screen reader users how the combobox will respond when typing in the input field. If set, it’s value must be one of the following tokens:

When the options in a listbox popup are filtered (aria-autocomplete set to either list or both), screen reader users should be aware of the current number of options available. That information is conveyed by default for a combobox using input with datalist> or a ul or ol element for a custom listbox. Otherwise, a custom combobox should dynamically set aria-setsize on the element with role=listbox and aria-posinset on the element with role=option.

The aria-disabled attribute should not be set on an element that supports the disabled attribute, which include the button, input, option and select elements. Use the disabled attribute directly. When using other elements to implement a custom combobox, the aria-disabled value, true or false (default), must correspond to its operational state.

If a combobox is editable but some entries may be rejected as invalid by the author’s code, aria-invalid attribute should be set on the combobox input with an invalid entry and a suggestion for correction should be provided, if one is known. The correction message should be referenced by the [ aria-errormessage] on the input.

The combobox input must be the only widget element in the tab sequence.

For listbox, grid, and tree popups, keyboard focus should remain on the input element while operating. A custom combobox should follow the ARIA Authoring Practices Guide “Developing a Keyboard Interface” by implementing keyboard event handlers to navigate popup interactive elements with arrow keys.

Keyboard focus should be transferred to a dialog popup for navigation using the Tab key within the dialog’s internal tab sequence. When the dialog is closed, keyboard focus should return to the combobox input.

Keyboard users must be able to operate all functions of the combobox.

Interactive HTML elements, such as buttons and input fields, provide keyboard operation by default for their native behavior. For example, a click event occurs on a button when activated with a mouse, a tap or double tap on a touch screen, or an Enter key when the button is focused or can perform a form submission. When using custom elements, explicit event handlers are needed to enable keyboard users to fully use the combobox.

Use the keydown and keyup events to trigger actions. Avoid the keypress event.

A combobox should follow common conventions. One such convention is to expand the popup with the ArrowDown. Because a combobox is a form control and the Enter key typically submits a form, users will generally avoid using the Enter key to expand the popup, even when it is a dialog.

The following conventions are common for listbox, grid, and tree popups, where keyboard focus remains on the combobox inputs.

Additional keyboard actions may be needed or desired to navigate an expanded popup, depending on the nature of the popup.

The combobox element must receive keyboard focus when it is clicked to enable text entry or option selection with a keyboard. Focus should occur when clicked if the combobox is a valid form control (which it must be) without the need for an additional event handler in a custom combobox.

Users should be able to expand the popup and make a selection using a mouse, a touch screen, a sip and puff switch or any other pointer device. A custom combobox event handler may be needed to ensure that the popup upens on either the initial or subsequent click.

An option should become active and highlighted but not selected when hovered and, for the benefit of touch interface users, also on the pointerdown event. The active option should change when a user moves the pointer in the down state to a different option. Action on both pointerover and pointerdown events may be necessary.

Option selection should occur on the pointerup event, allowing users to move the pointer while it is down to their desired option. Note that a click event on a touch interface only occurs with a quick tap and may not occur with all interactions.

A change of context or other consequential action must not occur when selecting an option or setting a value for the input without clear prior warning of that action. Because some users may accidentally set a value or navigate away from an incomplete entry because of a distraction or to get further information, best practice is to rely on the standard form behavior to perform a consequential action with a submit button or Enter key.

Further, keyboard focus must remain on the combobox input while editing the input or navigating a listbox, grid, or tree popup. (Focus goes into a dialog popup while it is open, then returns to the combobox when closed.)

A popup should not be made available if it has nothing to select, which often happens when autocomplete behavior has found no option matching a typed entry.

Conflicting ARIA settings can lead to unexpected or annoying behavior.

To avoid possible conflicts with how semantic HTML element roles and properties are exposed to assistive technologies, do not set ARIA attributes or assign roles that are redundant.

Explicit ARIA settings should not be set that conflict with native HTML accessibility mappings.