Listbox Pattern

About This Pattern

A listbox widget presents a list of options and allows a user to select one or more of them. A listbox that allows a single option to be chosen is a single-select listbox; one that allows multiple options to be selected is a multi-select listbox.

When screen readers present a listbox, they may render the name, state, and position of each option in the list. The name of an option is a string calculated by the browser, typically from the content of the option element. As a flat string, the name does not contain any semantic information. Thus, if an option contains a semantic element, such as a heading, screen reader users will not have access to the semantics. In addition, the interaction model conveyed by the listbox role to assistive technologies does not support interacting with elements inside of an option. Because of these traits of the listbox widget, it does not provide an accessible way to present a list of interactive elements, such as links, buttons, or checkboxes. To present a list of interactive elements, see the Grid Pattern.

Avoiding very long option names facilitates understandability and perceivability for screen reader users. The entire name of an option is spoken as a single unit of speech when the option is read. When too much information is spoken as the result of a single key press, it is difficult to understand. Long names inhibit perception by increasing the impact of interrupted speech because users typically have to re-read the entire option. And, if the user does not understand what is spoken, reading the name by character, word, or phrase may be a difficult operation for many screen reader users in the context of a listbox widget.

Sets of options where each option name starts with the same word or phrase can also significantly degrade usability for keyboard and screen reader users. Scrolling through the list to find a specific option becomes inordinately time consuming for a screen reader user who must listen to that word or phrase repeated before hearing what is unique about each option. For example, if a listbox for choosing a city were to contain options where each city name were preceded by a country name, and if many cities were listed for each country, a screen reader user would have to listen to the country name before hearing each city name. In such a scenario, it would be better to have 2 list boxes, one for country and one for city.

Examples

Keyboard Interaction

For a vertically oriented listbox:

Note

  1. DOM focus (the active element) is functionally distinct from the selected state. For more details, see this description of differences between focus and selection.
  2. The listbox role supports the aria-activedescendant property, which provides an alternative to moving DOM focus among option elements when implementing keyboard navigation. For details, see Managing Focus in Composites Using aria-activedescendant.
  3. In a single-select listbox, moving focus may optionally unselect the previously selected option and select the newly focused option. This model of selection is known as "selection follows focus". Having selection follow focus can be very helpful in some circumstances and can severely degrade accessibility in others. For additional guidance, see Deciding When to Make Selection Automatically Follow Focus.
  4. If selecting or unselecting all options is an important function, implementing separate controls for these actions, such as buttons for "Select All" and "Unselect All", significantly improves accessibility.
  5. If the options in a listbox are arranged horizontally:
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
    2. Up Arrow performs as Left Arrow is described above, and vice versa.

WAI-ARIA Roles, States, and Properties

Note

  1. Some factors to consider when choosing whether to indicate selection with aria-selected or aria-checked are:
    • Some design systems use aria-selected for single-select widgets and aria-checked for multi-select widgets. In the absence of factors that would make an alternative convention more appropriate, this is a recommended convention.
    • The language of instructions and the appearance of the interface might suggest one attribute is more appropriate than the other. For instance, do instructions say to select items? Or, is the visual indicator of selection a check mark?
    • It is important to adopt a consistent convention for selection models across a site or app.
  2. Conditions that would permit a listbox to include both aria-selected and aria-checked are extremely rare. It is strongly recommended to avoid designing a listbox widget that would have the need for more than one type of state. If both states were to be used within a listbox, all the following conditions need to be satisfied:
    • The meaning and purpose of aria-selected is different from the meaning and purpose of aria-checked in the user interface.
    • The user interface makes the meaning and purpose of each state apparent.
    • The user interface provides a separate method for controlling each state.
  3. If aria-owns is set on the listbox element to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order.