Legacy ARIA 1.0 Combobox With Both List and Inline Autocomplete Example

NOTE: Please provide feedback in issue 553.

The below combobox for choosing the name of a US state or territory demonstrates the ARIA 1.0 design pattern for combobox. 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:

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

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 design pattern.

Textbox

Key Function
Down Arrow
  • If the listbox is displayed and a suggestion is selected, moves visual focus to the next suggested value.
  • If the textbox is empty and the listbox is not displayed, opens the listbox and moves visual focus to the first option.
  • In both cases DOM focus remains on the textbox.
Up Arrow
  • If the listbox is displayed and a suggestion is selected, moves visual focus to the last suggested value.
  • If the textbox is empty, first opens the listbox if it is not already displayed and then moves visual focus to the last option.
  • In both cases DOM focus remains on the textbox.
Enter
  • Sets the textbox value to the content of the selected option.
  • Closes the listbox.
Escape
  • Clears the textbox.
  • If the listbox is displayed, closes it.
Standard single line text editing keys
  • Keys used for cursor movement and text manipulation, such as Delete and Shift + Right Arrow.
  • An HTML input with type="text" is used for the textbox so the browser will provide platform-specific 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 Using aria-activedescendant to Manage Focus.

Key Function
Enter
  • Sets the textbox value to the content of the focused option in the listbox.
  • Closes the listbox.
  • Sets visual focus on the textbox.
Escape
  • Clears the textbox.
  • Closes the listbox.
  • Sets visual focus on the textbox.
Down Arrow
  • Moves visual focus to the next option.
  • If visual focus is on the last option, moves visual focus to the first option.
  • Note: This wrapping behavior is useful when Home and End move the editing cursor as described below.
Up Arrow
  • Moves visual focus to the previous option.
  • If visual focus is on the first option, moves visual focus to the last option.
  • Note: This wrapping behavior is useful when Home and End move the editing cursor as described below.
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
  • Moves visual focus to the textbox.
  • Types the character in the textbox.

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 design pattern.

Textbox

Role Attribute Element Usage
combobox input[type="text"]
  • Identifies the input as a combobox.
  • Note: The primary difference between the ARIA 1.0 pattern and the ARIA 1.1 pattern is the placement of the combobox role.
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-haspopup="true" input[type="text"] Indicates that the combobox can popup another element to suggest values.
aria-owns="#IDREF" input[type="text"]
  • Identifies the element that serves as the popup.
  • Note: In the ARIA 1.1 combobox pattern, the combobox uses aria-controls instead of aria-owns.
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.
aria-activedescendant="IDREF" input[type="text"]
  • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the input element.
  • For more information about this focus management technique, see Using aria-activedescendant to Manage Focus.

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
  • Identifies the element as a listbox option.
  • The text content of the element provides the accessible name of the option.
aria-selected="true" li
  • Specified on an option in the listbox when it is visually highlighted as selected.
  • Occurs when an option in the list is referenced by aria-activedescendant and when focus is in the textbox and the first option is automatically selected.

Javascript and CSS Source Code

HTML Source Code