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 two example implementations of the Listbox Pattern demonstrate differences between single-select and multi-select functionality. In both examples, users can use action buttons to move options from one list to another. In the first implementation, users can choose a single option and then activate an action button while in the second example, they may select multiple options before activating an action button.
Similar examples include:
Example 1: Single-Select Listbox
Rank features important to you when choosing where to live. If a feature is unimportant, move it to the unimportant features list.
- Proximity of public K-12 schools
- Proximity of child-friendly parks
- Proximity of grocery shopping
- Proximity of fast food
- Proximity of fine dining
- Neighborhood walkability
- Availability of public transit
- Proximity of hospital and medical services
- Level of traffic noise
- Access to major highways
Example 2: Multi-Select Listbox
Choose upgrades for your transport capsule.
- Leather seats
- Front seat warmers
- Rear bucket seats
- Rear seat warmers
- Front sun roof
- Rear sun roof
- Cloaking capability
- Food synthesizer
- Advanced waste recycling system
- Turbo vertical take-off capability
Keyboard shortcuts for action buttons:
Action buttons have the following shortcuts:
- "Up": Alt + Up Arrow
- "Down": Alt + Down Arrow
- "Add": Enter
- "Not Important", "Important", and "Remove": Delete
- Availability of the shortcuts is communicated to assistive technologies via the
aria-keyshortcutsproperty on the button elements.
- Each shortcut is only captured when focus is in a context where it is relevant. For example, Enter performs an add only when focus is in the available options list, and Delete performs a remove only when focus is in the chosen options list.
- Using a shortcut key intentionally places focus to optimize both screen reader and keyboard usability. For example, pressing Alt + Up Arrow in the "Important Features" list keeps focus on the option that is moved up, enabling all keyboard users to easily perform consecutive move operations for an option and screen reader users to hear the position of an option after it is moved. Similarly, pressing Enter in the available options list leaves focus in the available options list. If the option that had focus before the add operation is no longer present in the list, focus lands on the first of the subsequent options that is still present.
- Action buttons have the following shortcuts:
- In example 1, since there are four action buttons, a toolbar widget is used to group all the action buttons into a single tab stop.
- Live regions provide confirmation of completed actions.
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 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.
NOTE: When visual focus is on an option in these implementations of listbox, 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.
Multiple selection keys supported in example 2
NOTE: The selection behavior demonstrated differs from the behavior provided by browsers for native HTML
<select multiple> elements.
The HTML select element behavior is to alter selection with unmodified up/down arrow keys, requiring the use of modifier keys to select multiple options.
This example demonstrates the multiple selection interaction model recommended in the Keyboard Interaction section of the Listbox Pattern, which does not require the use of modifier keys.
|Space||changes the selection state of the focused option .|
|Shift + Down Arrow||Moves focus to and selects the next option.|
|Shift + Up Arrow||Moves focus to and selects the previous option.|
|Control + Shift + Home||Selects from the focused option to the beginning of the list.|
|Control + Shift + End||Selects from the focused option to the end of the list.|
Control + A (All Platforms)
|Selects all options in the list. If all options are selected, unselects all options.|
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.|
||Applied to the element with the listbox role, it refers to the span containing its label.|
||Applied to the element with the listbox role, it puts the listbox in the tab sequence.|
||Identifies each selectable element containing the name of an option.|
||Removes the character entities used for the check mark, left arrow and right arrow from the accessibility tree to prevent them from being included in the accessible name of an option or button.|