Example Listboxes with Rearrangeable Options
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.
Similar examples include:
- Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML
select
withsize
attribute greater than one. - Collapsible Dropdown Listbox Example: Single-select collapsible listbox that expands when activated, similar to HTML
select
with the attributesize="1"
. - Listbox Example with Grouped Options: Single-select listbox with grouped options, similar to an HTML
select
withoptgroup
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.
- 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
Notes
- Assistive technologies are told which option in the list is visually focused by the value of
aria-activedescendant
:- DOM focus remains on the
listbox
element. - When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of
aria-activedescendant
on thelistbox
element. - If the
listbox
element does not contain any options,aria-activedescendant
does not have a value.
- DOM focus remains on the
- When Tab moves focus into either listbox:
- If none of the options are selected, the first option receives focus.
- If an option is selected, the selected option receives focus.
- Only one option may be selected at a time (have
aria-selected="true"
). -
As the user moves focus in the list, selection also moves.
That is, both the value of
aria-activedescendant
and the element that hasaria-selected="true"
change.
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
- Privacy cloque
- Food synthesizer
- Advanced waste recycling system
- Turbo vertical take-off capability
Notes
- Like in example 1, assistive technologies are told which option in the list is visually focused by the value of
aria-activedescendant
:- DOM focus remains on the
listbox
element. - When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of
aria-activedescendant
on thelistbox
element. - If the
listbox
element does not contain any options,aria-activedescendant
does not have a value.
- DOM focus remains on the
- When Tab moves focus into either listbox:
- If none of the options are selected, focus is set on the first option.
- If one or more options are selected, focus is set on the first selected option.
- Unlike example 1, more than one option may be selected at a time (have
aria-selected="true"
).- The multi-select capability is communicated to assistive technologies by setting
aria-multiselectable="true"
on thelistbox
element. - All option elements have a value set for
aria-selected
. - Selected options have
aria-selected
set totrue
and all others have it set tofalse
. - Keys that move focus do not change the selected state of an option.
- The multi-select capability is communicated to assistive technologies by setting
- Users can toggle the selected state of the focused option with Space or click.
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.
- 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.
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 Design Pattern.
Key | Function |
---|---|
Down Arrow |
|
Up Arrow |
|
Home |
|
End |
|
Multiple selection keys supported in example 2
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 | 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 Design 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 |
|
|
aria-activedescendant="ID_REF" |
ul |
|
|
role="option" |
li |
Identifies each selectable element containing the name of an option. | |
aria-selected="true" |
li |
|
|
aria-selected="false" |
li |
|
Javascript and CSS Source Code
- CSS: listbox.css
- Javascript: listbox.js
- Javascript: toolbar.js
- Javascript: listbox-rearrangeable.js
HTML Source Code
Example 1: Single-Select Listbox
Example 2: Multi-Select Listbox