(Deprecated) Collapsible Dropdown Listbox 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

Deprecation Warning

This pattern has been deprecated, and will be removed in a future version of the ARIA Authoring Practices. The select-only combobox should be used as an alternative to this pattern.

The following example implementation of the Listbox Pattern demonstrates a collapsible single-select listbox widget that is functionally similar to an HTML select input with the attribute size="1". The widget consists of a button that triggers the display of a listbox. In its default state, the widget is collapsed (the listbox is not visible) and the button label shows the currently selected option from the listbox. When the button is activated, the listbox is displayed and the current option is focused and selected.

Similar examples include:

Select-Only Combobox: A single-select combobox with no text input that is functionally similar to an HTML select element.
Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML select with size attribute greater than one.
Example Listboxes with Rearrangeable Options: Examples of both single-select and multi-select listboxes with accompanying toolbars where options can be added, moved, and removed.
Listbox Example with Grouped Options: Single-select listbox with grouped options, similar to an HTML select with optgroup children.

Example

Choose your favorite transuranic element (actinide or transactinide).

Accessibility Features

Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view.
To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes:
- To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the 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.

Keyboard Support

The example listbox 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 Listbox Pattern.

NOTE: When visual focus is on an option in this listbox implementation, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant.

Key	Function
`Tab`	Moves focus into and out of the listbox. If the listbox is expanded, selects the focused option, collapses the listbox, and moves focus out of the listbox.
`Enter`	If the focus is on the button, expands the listbox and places focus on the currently selected option in the list. If focus is in the listbox , collapses the listbox and keeps the currently selected option as the button label.
`Escape`	If the listbox is displayed, collapses the listbox and moves focus to the button.
`Down Arrow`	Moves focus to and selects the next option. If the listbox is collapsed, also expands the list.
`Up Arrow`	Moves focus to and selects the previous option. If the listbox is collapsed, also expands the list.
`Home`	If the listbox is displayed, moves focus to and selects the first option.
`End`	If the listbox is displayed, moves focus to and selects the last option.
Printable Characters	Type a character: focus moves to the next item with a name that starts with the typed character. Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.

Role, Property, State, and Tabindex Attributes

The example listbox 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 Listbox Pattern.

Role	Attribute	Element	Usage
	`aria-labelledby="ID_REF1 ID_REF2"`	`button`	References the two elements whose labels are concatenated by the browser to label the button. The first element is a span containing text Choose an element: . The second element is the button itself; the button text is set to the name of the currently chosen element.
	`aria-haspopup="listbox"`	`button`	Indicates that activating the button displays a listbox.
	`aria-expanded="true"`	`button`	Set by the JavaScript when the listbox is displayed. Otherwise, is not present.
`listbox`		`ul`	Identifies the focusable element that has listbox behaviors and contains the listbox options.
	`aria-labelledby="ID_REF"`	`ul`	Refers to the element containing the listbox label.
	`tabindex="-1"`	`ul`	Makes the listbox focusable. The JavaScript sets focus on the listbox when it is displayed.
	`aria-activedescendant="ID_REF"`	`ul`	When an option in the listbox is visually indicated as having keyboard focus, refers to that option. Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element. When navigation keys, such as `Down Arrow`, are pressed, the JavaScript changes the value. For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant.
`option`		`li`	Identifies each selectable element containing the name of an option.
	`aria-selected="true"`	`li`	Indicates that the option is selected. Applied to the element with role option that is visually styled as selected. The option with this attribute is always the same as the option that is referenced by aria-activedescendant because it is a single-select listbox where selection follows focus.

JavaScript and CSS Source Code

CSS: listbox.css
Javascript: listbox.js, listbox-collapsible.js