Skip to content

Example Listboxes with Rearrangeable Options

Example Listboxes with Rearrangeable 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.

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:

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:
    Last change:

    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
    • Cloaking capability
    • Food synthesizer
    • Advanced waste recycling system
    • Turbo vertical take-off capability
    Upgrades you have chosen:
      Last change:

      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.

      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.
      3. Live regions provide confirmation of completed actions.

      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 the next option.
      • In the example 1 single-select listboxes, also selects the focused option.
      Up Arrow
      • Moves focus to the previous option.
      • In the example 1 single-select listboxes, also selects the focused option.
      Home
      • Moves focus to the first option.
      • In the example 1 single-select listboxes, also selects the focused option.
      End
      • Moves focus to the last option.
      • In the example 1 single-select listboxes, also selects the focused option.

      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.

      Key Function
      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)
      Command-A (macOS)       		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.

      Role Attribute Element Usage
      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
      • Used only in example 2.
      • 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="".
      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, 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.
      • In example 2, more than one option may be selected so the user can move focus among options without effecting which options have this attribute.
      • Note that in example 2, the focus style and selection styles are distinctly different and independent.
      aria-selected="false" li
      • Used only in example 2.
      • 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 unnecessary because the selection moves every time the focus moves.

      JavaScript and CSS Source Code

      HTML Source Code

      Example 1: Single-Select Listbox

      Example 2: Multi-Select Listbox

      Back to Top

      This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.