Editable Combobox With Both List and Inline Autocomplete Example
Read This First
The code in this example is not intended for production environments.
Before using it for any purpose, read this to understand why.
This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.
- There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. Testing code based on this example with assistive technologies is essential before considering use in production systems.
- The ARIA and Assistive Technologies Project is developing measurements of assistive technology support for APG examples.
- Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.
About This Example
The below combobox for choosing the name of a US state or territory demonstrates the Combobox Pattern. The design pattern describes four types of autocomplete behavior. This example illustrates the autocomplete behavior referred to in the pattern as list with inline completion. If the user types one or more characters in the edit box and the typed characters match the beginning of the name of one or more states or territories, a listbox popup appears containing the matching names, and the first match is automatically selected. In addition, the portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox. The automatically selected suggestion becomes the value of the textbox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the textbox. Note that this implementation enables users to input the name of a state or territory, but it does not prevent input of any other arbitrary value.
Similar examples include:
- Select-Only Combobox: A single-select combobox with no text input that is functionally similar to an HTML
select
element. - Editable Combobox with List Autocomplete: An editable combobox that demonstrates the autocomplete behavior known as
list with manual selection
. - Editable Combobox Without Autocomplete: An editable combobox that demonstrates the behavior associated with
aria-autocomplete=none
. - Editable Combobox with Grid Popup: An editable combobox that presents suggestions in a grid, enabling users to navigate descriptive information about each suggestion.
- Date Picker Combobox: An editable date input combobox that opens a dialog containing a calendar grid and buttons for navigating by month and year.
Example
- Alabama
- Alaska
- American Samoa
- Arizona
- Arkansas
- California
- Colorado
- Connecticut
- Delaware
- District of Columbia
- Florida
- Georgia
- Guam
- Hawaii
- Idaho
- Illinois
- Indiana
- Iowa
- Kansas
- Kentucky
- Louisiana
- Maine
- Maryland
- Massachusetts
- Michigan
- Minnesota
- Mississippi
- Missouri
- Montana
- Nebraska
- Nevada
- New Hampshire
- New Jersey
- New Mexico
- New York
- North Carolina
- North Dakota
- Northern Marianas Islands
- Ohio
- Oklahoma
- Oregon
- Pennsylvania
- Puerto Rico
- Rhode Island
- South Carolina
- South Dakota
- Tennessee
- Texas
- Utah
- Vermont
- Virginia
- Virgin Islands
- Washington
- West Virginia
- Wisconsin
- Wyoming
Accessibility Features
- Browsers do not manage visibility of elements referenced by aria-activedescendant like they do for elements with focus. When a keyboard event changes the active option in the listbox, the JavaScript scrolls the option referenced by aria-activedescendant into view. Managing aria-activedescendant visibility is essential to accessibility for people who use a browser's zoom feature to increase the size of content.
-
To enhance perceivability when operating the combobox, visual keyboard focus and hover are styled using the CSS
:hover
pseudo-class, andfocus
andblur
event handlers:- To make it easier to perceive when the combobox receives focus, focus creates a 2 pixel focus ring around both the
input
andbutton
elements with 2 pixels of space between the focus ring and the combobox. - To make it easier to perceive that either the input or button can be clicked to open the listbox, hover causes the same styling as focus.
- To help people with visual impairments identify the combobox as an interactive element, the cursor is changed to a pointer when hovering over the combobox or list.
- To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.
- Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements. Instead of using transparency, the focused element has a thicker border and less padding. When an element receives focus, its border changes from zero to two pixels and padding is reduced by two pixels. When an element loses focus, its border changes from two pixels to two and padding is increased by two pixels.
- To make it easier to perceive when the combobox receives focus, focus creates a 2 pixel focus ring around both the
-
To ensure the inline SVG graphic used for the arrow in the open button has sufficient contrast with the background when high contrast settings change the color of text content, CSS
forced-color-adjust
is set toauto
on thesvg
element and and thefill
attribute of thepolygon
element is set tocurrentcolor
. This causes the colors of thefill
of the polygon elements to be overridden by the high contrast color setting. Ifforced-color-adjust
were not used to override the colors specified for thefill
property, the color would remain the same in high contrast mode, which could lead to insufficient contrast between the arrow and the background or even make it invisible if the color matched the high contrast mode background.
Note: The explicit setting offorced-color-adjust
is necessary because some browsers do not useauto
as the default value for SVG graphics.
Keyboard Support
The example combobox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Combobox Pattern.
Textbox
Key | Function |
---|---|
Down Arrow |
|
Alt + Down Arrow | Opens the listbox without moving focus or changing selection. |
Up Arrow |
|
Enter |
|
Escape |
|
Standard single line text editing keys |
|
Listbox Popup
NOTE: When visual focus is in the listbox, DOM focus remains on the textbox and the value of aria-activedescendant
on the textbox is set to a value that refers to the listbox option that is visually indicated as focused.
Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator.
For more information about this focus management technique, see
Managing Focus in Composites Using aria-activedescendant.
Key | Function |
---|---|
Enter |
|
Escape |
|
Down Arrow |
|
Up Arrow |
|
Right Arrow | Moves visual focus to the textbox and moves the editing cursor one character to the right. |
Left Arrow | Moves visual focus to the textbox and moves the editing cursor one character to the left. |
Home | Moves visual focus to the textbox and places the editing cursor at the beginning of the field. |
End | Moves visual focus to the textbox and places the editing cursor at the end of the field. |
Printable Characters |
|
Button
The button has been removed from the tab sequence of the page, but is still important to assistive technologies for mobile devices that use touch events to open the list of options.
Role, Property, State, and Tabindex Attributes
The example combobox on this page implements the following ARIA roles, states, and properties. Information about other ways of applying ARIA roles, states, and properties is available in the Roles, States, and Properties section of the Combobox Pattern.
Textbox
Role | Attribute | Element | Usage |
---|---|---|---|
combobox
|
input[type="text"] |
Identifies the input as a combobox. | |
aria-autocomplete="both"
|
input[type="text"] |
Indicates that the autocomplete behavior of the text input is to both show an inline completion string and suggest a list of possible values in a popup where the suggestions are related to the string that is present in the textbox. | |
aria-controls="ID_REF"
|
input[type="text"] |
Identifies the element that serves as the popup. | |
aria-expanded="false"
|
input[type="text"] |
Indicates that the popup element is not displayed. | |
aria-expanded="true"
|
input[type="text"] |
Indicates that the popup element is displayed. | |
id="string"
|
input[type="text"] |
|
|
aria-activedescendant="ID_REF"
|
input[type="text"] |
|
Listbox Popup
Role | Attribute | Element | Usage |
---|---|---|---|
listbox
|
ul
|
Identifies the ul element as a listbox . |
|
aria-label="States"
|
ul |
Provides a label for the listbox . |
|
option
|
li |
|
|
aria-selected="true"
|
li |
|
Button
Role | Attribute | Element | Usage |
---|---|---|---|
tabindex="-1"
|
button |
Removes the button from the tab sequence of the page because its function is redundant with the keyboard operation of the combobox. | |
aria-label="States"
|
button |
Provides a label for the button . |
|
aria-controls="ID_REF"
|
button |
Identifies the element that serves as the popup. | |
aria-expanded="false"
|
button |
Indicates that the popup element is not displayed. | |
aria-expanded="true"
|
button |
Indicates that the popup element is displayed. |
Javascript and CSS Source Code
- CSS: combobox-autocomplete.css
- Javascript: combobox-autocomplete.js
HTML Source Code