Multiselect Listbox Example

About This Example

This example demonstrates a multiselect listbox widget following the Listbox Pattern with the aria-multiselectable property. This widget allows the selection of one or more options from a list and is functionally similar to an HTML select element with the multiple attribute.

Example

Listbox:

(Note: Checkmark icons, etc., may also be used to visually indicate selected options.)

Keyboard Interaction

Tab: Moves focus into and out of the listbox. When focus moves into the listbox, it is placed on the first selected option, or the first option if none is selected.
Down Arrow: Moves focus to the next option without changing selection.
Up Arrow: Moves focus to the previous option without changing selection.
Space: Toggles the selection state of the focused option.
Enter, Esc: If the listbox was opened from a button or combobox, closes the listbox.

Roles, States, and Properties

The element that contains or owns the options has role listbox.
The element with role listbox has aria-labelledby or aria-label.
The element with role listbox has aria-multiselectable set to true.
Each option has role option.
Each selected option has both aria-checked and aria-selected set to true (see Note).
All options that are not selected have both aria-checked and aria-selected set to false (see Note).

Note

The Listbox Pattern recommends using aria-checked for multiselect listboxes and recommends against using both aria-checked and aria-selected. However, this is not supported by current, leading screen readers, JAWS 2024 and NVDA 2024:

Both screen readers say "not selected" if aria-selected is undefined, so options with only aria-checked="true" are indciated as "checked, not selected", which is incorrect.
Neither screen reader says "selected" if aria-selected="true", making it difficult to identify selected options if only aria-selected is used. (This behavior is designed for single-select listboxes where selection follows focus and "selected" is implied.)

Until leading screen readers change the above behaviors, the only effective solution appears to be to use both aria-checked and aria-selected.

Reference Example

For comparison, the following example is an HTML Select with the multiple attribute. In most desktop browsers, users must hold the Ctrl key to move between or make multiple selections, which is confusing and error-prone. As with aria-selected, leading screen readers do not explicitly say which options are selected.

Select: