docs.rodeo

MDN Web Docs mirror

ARIA: listbox role

{{AccessibilitySidebar}} 

The listbox role is used for lists from which a user may select one or more items which are static and, unlike HTML {{HTMLElement('select')}}  elements, may contain images.

Description

The listbox role is used to identify an element that creates a list from which a user may select one or more static items, similar to the HTML {{HTMLElement('select')}}  element. Unlike {{HTMLElement('select')}} , a listbox can contain images. Listboxes contain children whose role is option or elements whose role is group which in turn contain children whose role is option.

It is highly recommended using the HTML select element, or a group of radio buttons if only one item can be selected, or a group of checkboxes if multiple items can be selected, because there is a lot of keyboard interactivity to manage focus for all the descendants, and native HTML elements provide this functionality for you for free.

Elements with the role listbox have an implicit aria-orientation value of vertical.

When a list is tabbed to, the first item in the list will be selected if nothing else already is. Up/down arrows navigate the list, and pressing Shift + Up/Down arrows will move and extend the selection. Typing one or more letters will navigate the list items (same letter goes to each item starting with that, different letters go to the first item starting with that entire string). If the current item has an associated context menu, Shift+F10 will launch that menu. If list items are checkable, Space can be used to toggle checkboxes. For selectable list items, Space toggles their selection, Shift+Space can be used to select contiguous items, Ctrl+Arrow moves without selecting, and Ctrl+Space can be used to select non-contiguous items. It is recommended that a checkbox, link or other method be used to select all items, and Ctrl+A could be used as a shortcut key for this.

When the listbox role is added to an element, or such an element becomes visible, screen readers announce the label and role of the listbox when it gets focus. If an option or item is focused within the list, it gets announced next, followed by an indication of the item’s position with the list if the screen reader supports this. As focus moves within the list, the screen reader announces the relevant items.

Associated ARIA roles, states, and properties

Associated Roles

States and Properties

Keyboard interactions

Required JavaScript features

selecting an option in a single select listbox

When the user selects an option, the following must occur:

  1. Deselect the previously selected option, setting the aria-selected to false, or removing the attribute altogether, changing the appearance of the newly unselected option to appear not selected.
  2. Select the newly selected option, setting aria-selected="true" on the option and changing the appearance of the newly selected option to appear selected.
  3. Update the aria-activedescendant value on the listbox to the id of the newly selected option
  4. Visually handle the blur, focus, and selected states of the option

Toggling the state of an option in a multi select listbox

When the user clicks on an option, hits Space when focused on an option, or otherwise toggles the state of an option, the following must occur:

  1. Toggle the aria-selected state of the currently focused option, changing the state of the aria-selected to true if it was false or false if it was true.
  2. Change the appearance of the option to reflect its selected state
  3. Update the aria-activedescendant value on the listbox to the ID of the option the user just interacted with, even if they toggled the option to be unselected.

[!NOTE] The first rule of ARIA use is you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so. The {{HTMLElement('select')}}  element with descendant {{HTMLElement('option')}}  elements handles all the needed interactions natively.

Examples

Example 1: A single select listbox that uses aria-activedescendant

The snippet below, using aria-activedescendant, shows how the listbox role is added directly into the HTML source code.

<p id="listbox1label" role="label">Select a color:</p>
<div
  role="listbox"
  tabindex="0"
  id="listbox1"
  aria-labelledby="listbox1label"
  onclick="return listItemClick(event);"
  onkeydown="return listItemKeyEvent(event);"
  onkeypress="return listItemKeyEvent(event);"
  aria-activedescendant="listbox1-1">
  <div role="option" id="listbox1-1" class="selected" aria-selected="true">
    Green
  </div>
  <div role="option" id="listbox1-2">Orange</div>
  <div role="option" id="listbox1-3">Red</div>
  <div role="option" id="listbox1-4">Blue</div>
  <div role="option" id="listbox1-5">Violet</div>
  <div role="option" id="listbox1-6">Periwinkle</div>
</div>

This could have more easily been handled with the native HTML {{HTMLElement('select')}}  and {{HTMLElement('label')}}  elements.

<label for="listbox1">Select a color:</label>
<select id="listbox1">
  <option selected>Green</option>
  <option>Orange</option>
  <option>Red</option>
  <option>Blue</option>
  <option>Violet</option>
  <option>Periwinkle</option>
</select>

More examples

Best practices

Specifications

{{Specifications}} 

See also

In this article

View on MDN