Using the listbox role

Description

This technique demonstrates how to use the listbox role and describes the effect it has on browsers and assistive technology.

The listbox role is used to identify an element that creates a list from which a user may select one or more items which are static and, unlike HTML <select> elements, may contain images. When the role is added to an element, the browser will send out an accessible listbox event to assistive technology products which can then notify the user about it.

Each entry in the listbox should have a role of option and should be DOM children of listbox. If one or more entries are not DOM children of listbox, please see the ARIA best practices for details of additional properties that may need to be set.

When a list is tabbed to, the first item in the list will be selected if nothing else already is. Up/down arrows navigate the list, and pressing Shift + Up/Down arrows will move and extend the selection. Typing one or more letters will navigate the list items (same letter goes to each item starting with that, different letters go to the first item starting with that entire string). If the current item has an associated context menu, Shift+F10 will launch that menu. If list items are checkable, Space can be used to toggle checkboxes. For selectable list items, Space toggles their selection, Shift+Space can be used to select contiguous items, Ctrl+Arrow moves without selecting, and Ctrl+Space can be used to select non-contiguous items. It is recommended that a checkbox, link or other method be used to select all items, and Ctrl+A could be used as a shortcut key for this.

Possible effects on user agents and assistive technology

When the listbox role is added to an element, or such an element becomes visible, the user agent should do the following:

Expose the element as having a listbox role in the operating system's accessibility API. Alternatively, if it is the child of or owned by a combobox, expose the element as a menu.
Fire an accessible listbox (or in special cases, menu) event using the operating system's accessibility API if it supports it.

Assistive technology products should listen for such an event and notify the user accordingly:

Screen readers should announce the label and role of the listbox when it gains focus. If an item is focused within the list, this should be announced next, followed by an indication of the item's position with the list if the screen reader supports this. As focus moves within the list, the screen reader should announce the relevant list items.
Screen magnifiers may enlarge the listbox.

Note: Opinons may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

Examples

Example 1: A single select listbox that uses aria-activedescendant

The snippet below shows how the listbox role is added directly into the html source code.

<div role="listbox" tabindex="0" id="listbox1" onclick="return listItemClick(event);" 
  onkeydown="return listItemKeyEvent(event);" onkeypress="return listItemKeyEvent(event);" 
  onfocus="this.className='focus';" onblur="this.className='blur';" aria-activedescendant="listbox1-1">
  <div role="option" id="listbox1-1" class="selected">Green</div>
  <div role="option" id="listbox1-2">Orange</div>
  <div role="option" id="listbox1-3">Red</div>
  <div role="option" id="listbox1-4">Blue</div>
  <div role="option" id="listbox1-5">Violet</div>
  <div role="option" id="listbox1-6">Periwinkle</div>
</div>

Working Examples:

Previous examples are now down. New examples needed.

Notes

To be keyboard accessible, authors should manage focus of all descendants of this role.
It is recommended that authors use different styling for the selection when the list is not focused, e.g. a non-active selection is often shown with a lighter background colour.
If the listbox is not part of another widget, it should have the aria-labelledby property set.
If one or more entries are not DOM children of listbox, additional aria-* properties will need to be set (see ARIA Best Practices).
If there is a valid reason to expand the listbox, the combobox role may be more appropriate.

ARIA attributes used

listbox

Related ARIA techniques

combobox role

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources

ARIA Best Practices – Listbox: https://www.w3.org/TR/wai-aria-practices/#listbox_div
ARIA Role Model – Listbox: https://www.w3.org/TR/wai-aria/roles#listbox