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
Similar examples include:
- Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML
sizeattribute 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.
- Winged Horse
So, when a keyboard or pointer event changes the option referenced by
To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS
- 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.
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.
|Tab||Moves focus into and out of the listbox.|
|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.
||Identifies the focusable element that has listbox behaviors and contains the listbox options.|
||Refers to the element containing the listbox label.|
||Includes the listbox in the page tab sequence.|
||Identifies a group of related options|
||Refers to the element containing the option group label.|
||Identifies each selectable element containing the name of an option.|
||Removes the character entity used for the check mark icon from the accessibility tree to prevent it from being included in the accessible name of the option.|