Listbox Example with Grouped Options

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 following example implementation of the Listbox Pattern demonstrates a single-select listbox widget with grouped options. This widget is functionally similar to an HTML select element with size greater than 1 and options grouped into categories with labeled optgroup elements.

Similar examples include:

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.

Example

Choose your animal sidekick

Notes

This listbox is scrollable; it has more options than its height can accommodate.

Scrolling only works as expected if the listbox is the options' offsetParent. The example uses position: relative on the listbox to that effect.
When an option is focused that isn't (fully) visible, the listbox's scroll position is updated:
1. If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
2. If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
3. If focusItem is called, the focused option will be scrolled to the top of the view if it was located above it or to the bottom if it was below it.
4. If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
When a fully visible option is focused in any way, no scrolling occurs.
Normal scrolling through any scrolling mechanism (including Page Up and Page Down) works as expected. The scroll position will jump as described for focusItem if a means other than a mouse click is used to change focus after scrolling.

Accessibility Features

The listbox 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.
Navigating the list of options does not set the selection of an option. This gives screen reader users, who need to navigate among the options to perceive them, the ability to explore options without changing the currently selected options. The value is set when users press Space or Enter. Selected options have a check preceding the text label for the option.
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 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 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.

Keyboard Support

The example listboxes on this page implement the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

Key	Function
`Down Arrow`	Moves focus to and selects the next option.
`Up Arrow`	Moves focus to and selects the previous option.
`Home`	Moves focus to and selects the first option.
`End`	Moves focus to and selects the last option.

Role, Property, State, and Tabindex Attributes

The example listboxes on this page implement 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
`listbox`		`div`	Identifies the focusable element that has listbox behaviors and contains the listbox options.
	`aria-labelledby="ID_REF"`	`div`	Refers to the element containing the listbox label.
	`tabindex="0"`	`div`	Includes the listbox in the page tab sequence.
	`aria-activedescendant="ID_REF"`	`div`	Tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus. DOM focus remains on the `ul` element and the idref specified for `aria-activedescendant` refers to the `li` element that is visually styled as focused. When navigation keys, such as `Down Arrow`, are pressed, the JavaScript changes the value.
`group`		`ul`	Identifies a group of related options
	`aria-labelledby="ID_REF"`	`ul`	Refers to the element containing the option group label.
`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-scrollable.js, utils.js