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.

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:

Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML select with size attribute greater than one.
Listbox Example with Grouped Options: Single-select listbox with grouped options, similar to an HTML select with optgroup children.

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:

Unimportant Features:

Last change:

Example 2: Multi-Select Listbox

Choose upgrades for your transport capsule.

Available upgrades:

Upgrades you have chosen:

Last change:

Accessibility Features

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-keyshortcuts property 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.
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.
Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view.
To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes:
- 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.

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.

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.

Key	Function
`Tab`	Moves focus into and out of the listbox. When the listbox receives focus, if none of the options are selected, the first option receives focus. Otherwise, the first selected option receives focus.
`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.
Printable Characters	Type a character: focus moves to the next item with a name that starts with the typed character. Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.

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`	When an option in the listbox is visually indicated as having keyboard focus, refers to that option. Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element. When navigation keys, such as `Down Arrow`, are pressed, the JavaScript changes the value. When the listbox is empty, `aria-activedescendant=""`. For more information about this focus management technique, see Managing Focus in Composites Using 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.
	`aria-hidden="true"`	`span`	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.

JavaScript and CSS Source Code

CSS: listbox.css
Javascript: listbox.js, toolbar.js, listbox-rearrangeable.js

HTML Source Code

Example 1: Single-Select Listbox

To copy the following HTML code, please open it in CodePen.

Example 2: Multi-Select Listbox

To copy the following HTML code, please open it in CodePen.