Skip to content

Select-Only Combobox Example

Select-Only Combobox 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.

About This Example

The following example implementation of the Combobox Pattern demonstrates a single-select combobox widget that is functionally similar to an HTML select element. Unlike the editable combobox examples, this select-only combobox is not made with an <input> element, and it does not accept freeform user input. However, like an HTML <select>, users can type characters to select matching options.

Similar examples include:

Example

Accessibility Features

While the functionality and user experience of this example are nearly equivalent to an HTML select element with the attribute size="1", the following differences in behavior are implemented to improve both accessibility and general usability.

  1. If the combobox is collapsed and the user types printable characters, the listbox is displayed and receives accessibility focus via aria-activedescendant. This enables users to perceive the presence of the options, and enables assistive technology users to comprehend the size of the list of options.
  2. Navigating the list of options does not set the value of the input. This gives screen reader users, who need to navigate among the options to perceive them, the ability to explore options without losing the current value of the input. The value is set when users press Space, Enter, or Tab, or when focus moves out of the combobox. The current value is retained if the listbox is closed with Escape or if the user collapses the list by clicking the input.
  3. 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.

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.

Closed Combobox

Key Function
Down Arrow
  • Opens the listbox if it is not already displayed without moving focus or changing selection.
  • DOM focus remains on the combobox.
Alt + Down Arrow Opens the listbox without moving focus or changing selection.
Up Arrow
  • First opens the listbox if it is not already displayed and then moves visual focus to the first option.
  • DOM focus remains on the combobox.
Enter Opens the listbox without moving focus or changing selection.
Space Opens the listbox without moving focus or changing selection.
Home Opens the listbox and moves visual focus to the first option.
End Opens the listbox and moves visual focus to the last option.
Printable Characters
  • First opens the listbox if it is not already displayed and then moves visual focus to the first option that matches the typed character.
  • If multiple keys are typed in quick succession, visual focus moves to the first option that matches the full string.
  • If the same character is typed in succession, visual focus cycles among the options starting with that character.

Listbox Popup

NOTE: When visual focus is in the listbox, DOM focus remains on the combobox and the value of aria-activedescendant on the combobox 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
  • Sets the value to the content of the focused option in the listbox.
  • Closes the listbox.
  • Sets visual focus on the combobox.
Space
  • Sets the value to the content of the focused option in the listbox.
  • Closes the listbox.
  • Sets visual focus on the combobox.
Tab
  • Sets the value to the content of the focused option in the listbox.
  • Closes the listbox.
  • Performs the default action, moving focus to the next focusable element. Note: the native <select> element closes the listbox but does not move focus on tab. This pattern matches the behavior of the other comboboxes rather than the native element in this case.
Escape
  • Closes the listbox.
  • Sets visual focus on the combobox.
Down Arrow
  • Moves visual focus to the next option.
  • If visual focus is on the last option, visual focus does not move.
Up Arrow
  • Moves visual focus to the previous option.
  • If visual focus is on the first option, visual focus does not move.
Alt + Up Arrow
  • Sets the value to the content of the focused option in the listbox.
  • Closes the listbox.
  • Sets visual focus on the combobox.
Home Moves visual focus to the first option.
End Moves visual focus to the last option.
PageUp Jumps visual focus up 10 options (or to first option).
PageDown Jumps visual focus down 10 options (or to last option).
Printable Characters
  • First opens the listbox if it is not already displayed and then moves visual focus to the first option that matches the typed character.
  • If multiple keys are typed in quick succession, visual focus moves to the first option that matches the full string.
  • If the same character is typed in succession, visual focus cycles among the options starting with that character.

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.

Combobox

Role Attribute Element Usage
combobox div Identifies the input as a combobox.
aria-labelledby="#IDREF" div Identifies the element that labels the combobox.
aria-controls="#IDREF" div Identifies the element that serves as the popup.
aria-expanded="false" div Indicates that the popup element is not displayed.
aria-expanded="true" div Indicates that the popup element is displayed.
aria-activedescendant="IDREF" div
  • 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 Managing Focus in Composites Using aria-activedescendant.

Listbox Popup

Role Attribute Element Usage
listbox div Identifies the element as a listbox.
option div
  • 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 only when an option in the list is referenced by aria-activedescendant.

Javascript and CSS Source Code

HTML Source Code

Back to Top

This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.