Listbox Example

This example page is incomplete; it is not ready for review. When ready, feedback will be welcome in issue 123.

The following two example implementations of the design pattern for listbox 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.

Examples

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.

Important Features:
  • 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
Unimportant Features:

Notes

  1. Assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant:
    1. DOM focus remains on the listbox element.
    2. When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
    3. If the listbox element does not contain any options, aria-activedescendant does not have a value.
  2. When Tab moves focus into either listbox:
    1. If none of the options are selected, the first option receives focus.
    2. If an option is selected, the selected option receives focus.
  3. Only one option may be selected at a time (have aria-selected="true").
  4. As the user moves focus in the list, selection also moves. That is, both the value of aria-activedescendant and the element that has aria-selected="true" change.

Example 2: Multi-Select Listbox

Choose upgrades for your transport capsule.

Available upgrades:
  • Leather seats
  • Front seat warmers
  • Rear bucket seats
  • Rear seat warmers
  • Front sun roof
  • Rear sun roof
  • Privacy cloque
  • Food synthesizer
  • Advanced waste recycling system
  • Turbo vertical take-off capability
Upgrades you have chosen:

Notes

  1. Like in example 1, assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant:
    1. DOM focus remains on the listbox element.
    2. When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
    3. If the listbox element does not contain any options, aria-activedescendant does not have a value.
  2. When Tab moves focus into either listbox:
    1. If none of the options are selected, focus is set on the first option.
    2. If one or more options are selected, focus is set on the first selected option.
  3. Unlike example 1, more than one option may be selected at a time (have aria-selected="true").
    1. The multi-select capability is communicated to assistive technologies by setting aria-multiselectable="true" on the listbox element.
    2. All option elements have a value set for aria-selected.
    3. Selected options have aria-selected set to true and all others have it set to false.
    4. Keys that move focus do not change the selected state of an option.
  4. Users can toggle the selected state of the focused option with Space or click.

Other Accessibility Features

  1. Keyboard shortcuts for action buttons:
    1. Action buttons have the following shortcuts:
      • "Up": Alt + Up Arrow
      • "Down": Alt + Down Arrow
      • "Add": Enter
      • "Not Important", "Important", and "Remove": Delete
    2. Availability of the shortcuts is communicated to assistive technologies via the aria-keyshortcuts property on the button elements.
    3. 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.
    4. 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.
  2. 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.

Keyboard Support

Multiple selection keys supported in example 2:

Role, Property, State, and Tabindex Attributes

Attribute Applied to Element Usage
role="listbox" ul Identifies the focusable element that has listbox behaviors and contains the listbox options.
aria-labelledby="ID_REF" ul Applied to the element with the listbox role, it refers to the span containing its label.
tabindex="0" ul Applied to the element with the listbox role, it puts the listbox in the tab sequence.
aria-multiselectable="true" ul Example 2 only: Applied to the element with the listbox role, tells assistive technologies that the list supports multiple selection. The default value is false so it is not specified in example 1.
aria-activedescendant="ID_REF" ul Applied to the element with the listbox role, 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. When the listbox is empty, aria-activedescendant="".
role="option" li Identifies each selectable element containing the name of an option.
aria-selected="true" li Applied to elements with role option that are visually styled as selected to inform assistive technologies that the options are selected. In example 1, this is always the same option that is referenced by aria-activedescendant because it is a single-select listbox where selection follows focus. In example 2, more than one option may be selected so the user can move focus among options without effecting which options are selected. Thus in example 2, the focus style and selection styles are distinctly different and independent.
aria-selected="false" li Example 2 only: Applied to elements with role option that are not visually styled as selected to inform assistive technologies that the options are selectable but not selected. In example 1, this is not necessary because the focus cannot move to an unselected option.

The following attributes are commonly useful when implementing the listbox design pattern but are not used in these examples.

Javascript and CSS Source Code

HTML Source Code

Example 1: Single-Select Listbox

Example 2: Multi-Select Listbox