# Listbox

> How to build an accessible listbox, native or custom, and the tests Evinced runs on its roles, names, selection, focus, and arrow-key navigation.

Source: https://knowledge.evinced.com/web/ui-patterns/listbox

A listbox lets users select one or more options from a list. An accessible listbox has the `listbox` ARIA role, an accessible name, and options that report their role, name, and selected state, with one tab stop and the arrow keys moving between options.

A listbox holds options, one for each choice, and can arrange them in labeled groups. Each option carries the `option` ARIA role and holds a static value that can be selected. An option's children are presentational and supply its default accessible name, so a heading, link, or button placed inside an option loses its meaning.

In a single-select listbox, choosing an option replaces the previous choice. In a multi-select listbox, users can select any number of options, and each option keeps its own selected state.

A **native listbox** is a `<select>` element with the `multiple` attribute or a `size` greater than 1. Without either, a `<select>` is a combobox whose popup is a listbox, as is an `<input>` with a `<datalist>`. Browsers convey all the information assistive technology needs for a native listbox with no ARIA attributes.

A **custom listbox** is built from other elements, with ARIA attributes and code that replicate or extend native listbox behavior.

Unlike a menu, whose items are commands that run immediately, a listbox holds values users choose for later use. [Related Patterns](https://knowledge.evinced.com/web/ui-patterns/listbox#related-patterns) lists other widgets that offer a choice, including the combobox, whose popup is often a listbox, and widgets better suited to a short set of options, such as a radio group or group of checkboxes.

## When to Use

Use a listbox when:

-   Users choose one or more values from a set of options, such as picking varieties of fruit for an order.
-   The list is long enough that radio buttons or checkboxes would crowd the page, and users benefit from scrolling it and typing a letter to jump to an option.
-   The options can be grouped in categories. Arrange them in labeled groups.
-   Each category holds many options, such as cities in many countries. Use two listboxes, where the choice in the first filters the options in the second, and name each option with its unique part first, such as "Dresden, Germany".
-   Space is limited and only the chosen value needs to show. Use a listbox as a combobox popup.

Do not use a listbox when:

-   There are only a few choices. Use a radio group or a group of checkboxes.
-   The items are commands that run when chosen. Use a menu.
-   The items are links, buttons, or other controls, or each item needs controls of its own. Use a list of links, or use the data grid pattern.

## Examples

Code in this section is meant to demonstrate techniques rather than requirements and lacks features needed in a production application.

A listbox is either a native `<select>` element or a custom widget built from generic elements with ARIA roles and code. Both examples group their options and allow a single selection. [Selected Options](https://knowledge.evinced.com/web/ui-patterns/listbox#selected-options) shows what a multi-select listbox adds.

### Native HTML select

A `size` greater than 1 displays several options at once and gives the `<select>` the `listbox` role. The `multiple` attribute, which allows more than one selection, does the same. Without either, the element has the `combobox` role and is rendered as a dropdown with a `listbox` popup.

Each `<optgroup>` is a group named by its `label` attribute, and the `selected` attribute marks the chosen option. The listbox takes its accessible name from its associated `<label>`, and the browser provides the keyboard behavior and reports the selection itself.

**Native listbox HTML**

```html
<label for="fruit-native">Fruit</label>
<select id="fruit-native" size="8">
  <optgroup label="Apples">
    <option>Braeburn</option>
    <option>Cox</option>
    <option selected>Granny Smith</option>
  </optgroup>
  <optgroup label="Oranges">
    <option>Blood Orange</option>
    <option>Navel</option>
    <option>Seville</option>
  </optgroup>
</select>
```

### Custom listbox with groups

The container carries `role="listbox"`, a name from `aria-labelledby`, and `tabindex="0"`, which makes the listbox a single stop in the tab order. Each group is named by the heading it contains, and the heading's `role="none"` keeps it from being exposed as an option. Every option has an `id` and an `aria-selected` state.

Keyboard focus stays on the listbox. The script points `aria-activedescendant` at the option that has focus and marks that option with a class, so CSS can give it a visible focus indicator that `:focus` can't provide. The arrow keys, Home, and End move focus, and Space or a click selects the focused option. The same script works for a multi-select listbox, where Space toggles an option.

**Custom listbox HTML**

```html
<span id="fruit-label">Fruit</span>
<div role="listbox" id="fruit" tabindex="0" aria-labelledby="fruit-label">
  <div role="group" aria-labelledby="apples-heading">
    <div role="none" id="apples-heading">Apples</div>
    <div role="option" id="braeburn" aria-selected="false">Braeburn</div>
    <div role="option" id="cox" aria-selected="false">Cox</div>
    <div role="option" id="granny-smith" aria-selected="true">Granny Smith</div>
  </div>
  <div role="group" aria-labelledby="oranges-heading">
    <div role="none" id="oranges-heading">Oranges</div>
    <div role="option" id="blood-orange" aria-selected="false">Blood Orange</div>
    <div role="option" id="navel" aria-selected="false">Navel</div>
    <div role="option" id="seville" aria-selected="false">Seville</div>
  </div>
</div>
```

**Custom listbox JavaScript**

For brevity, the following omits type-ahead, disabled options, and error checks.

```javascript
class Listbox {
  constructor(listbox) {
    this.listbox = listbox;
    this.multiple = listbox.getAttribute("aria-multiselectable") === "true";
    this.options = Array.from(listbox.querySelectorAll('[role="option"]'));


    listbox.addEventListener("focus", () => this.onFocus());
    listbox.addEventListener("keydown", (event) => this.onKeydown(event));
    listbox.addEventListener("click", (event) => this.onClick(event));
  }


  // Focus lands on the first selected option, or on the first option
  onFocus() {
    const selected = this.options.find(
      (option) => option.getAttribute("aria-selected") === "true"
    );
    this.setActive(selected ?? this.options[0]);
  }


  // Move effective focus with aria-activedescendant
  setActive(option) {
    this.options.forEach((item) =>
      item.classList.toggle("is-active", item === option)
    );
    this.listbox.setAttribute("aria-activedescendant", option.id);
    option.scrollIntoView({ block: "nearest" });
  }


  activeIndex() {
    const id = this.listbox.getAttribute("aria-activedescendant");
    return this.options.findIndex((option) => option.id === id);
  }


  // Single-select replaces the selection; multi-select toggles one option
  select(option) {
    if (this.multiple) {
      const selected = option.getAttribute("aria-selected") === "true";
      option.setAttribute("aria-selected", String(!selected));
    } else {
      this.options.forEach((item) =>
        item.setAttribute("aria-selected", String(item === option))
      );
    }
  }


  onKeydown(event) {
    const index = this.activeIndex();
    const last = this.options.length - 1;
    let next;


    switch (event.key) {
      case "ArrowDown":
        next = index >= last ? 0 : index + 1;
        break;
      case "ArrowUp":
        next = index <= 0 ? last : index - 1;
        break;
      case "Home":
        next = 0;
        break;
      case "End":
        next = last;
        break;
      case " ":
        event.preventDefault();
        if (index !== -1) {
          this.select(this.options[index]);
        }
        return;
      default:
        return;
    }


    event.preventDefault();
    this.setActive(this.options[next]);
  }


  // A click moves focus to the option and selects it
  onClick(event) {
    const option = event.target.closest('[role="option"]');


    if (option) {
      this.setActive(option);
      this.select(option);
    }
  }
}


const fruitListbox = new Listbox(document.getElementById("fruit"));
```

## Structure and Semantics

A listbox conveys its structure through roles. A container with the `listbox` role holds elements with the `option` role, either directly or inside elements with the `group` role. Assistive technology uses that structure to report how many options there are, where the user is among them, which group an option belongs to, and which options are selected.

A native `<select>` conveys all of this through HTML. Its `<optgroup>` and `<option>` elements carry the `group` and `option` roles, and the `selected` property and `disabled` attribute report their states, so a native listbox needs no ARIA. A custom listbox needs ARIA for each part:

| Attribute | How to use |
| :-- | :-- |
| `role` | Set to `"listbox"` on the container, `"option"` on each option, and `"group"` on each set of grouped options. |
| `aria-labelledby` or `aria-label` | Name the listbox and each group. A listbox that's the popup of a combobox takes the combobox's label through `aria-labelledby`. |
| `aria-selected` | Set to `"true"` on each selected option and `"false"` on every other selectable option. |
| `aria-multiselectable` | Set to `"true"` on the listbox when users can select more than one option. |
| `tabindex` | Set to `"0"` on the listbox when it uses `aria-activedescendant`, or on one option when it uses a roving tabindex. |
| `aria-activedescendant` | Set on the listbox to the `id` of the option that has focus. |
| `aria-orientation` | Set to `"horizontal"` when the options are laid out in a row. The default is `vertical`. |
| `aria-disabled` | Set to `"true"` on a disabled listbox, group, or option. |

The `option` role makes its content presentational, so an option is exposed only as its accessible name. Screen reader users hear the whole name each time an option receives focus, so keep option names short and put the part that tells them apart first.

A custom listbox isn't part of a form. To submit its selection with a form, make it a [form-associated custom element](https://html.spec.whatwg.org/dev/custom-elements.html#form-associated-custom-element) and set its value with `ElementInternals.setFormValue()`.

### Listbox has options

A listbox contains at least one option, and every group in it contains at least one option. Options sit directly inside the listbox or inside a group, and any other element inside the listbox, such as a group's heading, has `role="none"`.

**Offers at least one choice**

**Reported as:** No active options

A listbox must have at least one option that isn't disabled.

When every option is disabled, keyboard and screen reader users move through the list and find nothing that responds. They can't tell whether they missed the usable option, the listbox is broken, or there's no choice to make.

Keep at least one option available. When nothing can be chosen, disable the listbox itself, and say next to it why there's nothing to pick.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Contains elements with the option role**

**Reported as:** No group members with required role

A listbox and each of its groups must contain elements with the `option` role.

When the listbox's children are generic elements, or extra wrappers sit between the listbox and its options, assistive technology finds no options to report. Screen reader users are told they've reached a listbox, then hear its contents as unrelated text with no count or position.

Give each option `role="option"` and make it a child of the listbox or of a group. Remove any wrapper between them, or give the wrapper `role="none"`.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### Unexpected roles

A listbox holds only options, directly or inside groups. Assistive technology moves through a listbox option by option, so anything else among its children is skipped, or announced as something users can't choose.

**Admits only the expected roles**

**Reported as:** Unexpected interactive group members

A listbox must hold only elements with the `option` or `group` role.

When a button, a link or another element with its own role sits among the options, screen reader users moving through the list reach something they can't select, and the option count and positions they hear no longer add up.

Give each item the `option` role, put related options in a `group`, and move any other control out of the listbox, beside it.

**Severity:** Minor

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### Role

A listbox uses three roles: `listbox` on the container, `option` on each choice, and `group` on each set of grouped options. A native `<select>` with `multiple` or a `size` greater than 1 has the `listbox` role, and its `<optgroup>` and `<option>` elements carry `group` and `option`. A custom listbox declares each role itself.

**Has the correct role**

**Reported as:** Element has incorrect role

A listbox, its groups, and its options must each expose the role for their part: `listbox`, `group`, and `option`.

When a styled list of `<div>` elements has no roles, or its groups are generic wrappers, assistive technology exposes it as plain text. Users can't tell that it's a set of choices, how many options it has, or which group an option belongs to.

Use a native `<select>` with `<optgroup>` and `<option>` elements, or add `role="listbox"`, `role="group"`, and `role="option"` to a custom listbox.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Applies role to the correct element**

**Reported as:** Incorrect root element

**Sanity check.** Evinced checks that the `listbox` role sits on the element that holds the options and takes keyboard focus. This check runs on every UI pattern, not only on listboxes.

A custom listbox should carry the `listbox` role on the element that contains its options and manages focus among them, not on a wrapper around it or a descendant inside it.

When the role sits on one element while the tab stop and the key handling sit on another, assistive technology describes the focused element, which has no role. Users land on the listbox without being told what it is.

Put the `listbox` role, the accessible name, `aria-multiselectable`, and the key handling on one element, along with `tabindex` and `aria-activedescendant` when focus stays on the listbox. Keep any layout wrapper free of roles and handlers.

### Accessibility label

A standalone listbox has an accessible name that says what its options are for, such as "Fruit". A native `<select>` takes its name from an associated `<label>`, and a custom listbox points `aria-labelledby` at visible text or, when there's none, uses `aria-label`. A listbox that's the popup of a combobox needs a name too, and takes it from the combobox's label through `aria-labelledby`. [Combobox › Accessibility Label](https://knowledge.evinced.com/web/ui-patterns/combobox#accessibility-label) covers naming the popup.

**Names a container that needs one**

**Reported as:** Missing contextual labeling

A listbox, including one that's the popup of a combobox, must have an accessible name that says what its options are for.

When a listbox has no name, screen reader users hear "listbox" and a run of options with no indication of what choosing one does. On a page with several listboxes, they can't tell them apart.

Point `aria-labelledby` at the visible label, or associate a `<label>` with a native `<select>`. Use `aria-label` only when there's no visible text to reference, and name the listbox after what the choice is for, not after its kind.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### Options accessibility labels

Each option and each group in a listbox has an accessible name. An option usually takes its name from its text content, or from `aria-label` when that's present. A group takes its name from `aria-labelledby` pointing at its visible heading, as in the [Custom Listbox With Groups](https://knowledge.evinced.com/web/ui-patterns/listbox#custom-listbox-with-groups) example, and a native `<optgroup>` is named by its `label` attribute.

**Names each option and group of options**

**Reported as:** Group members missing accessible names

Every option and every group in a listbox must have an accessible name.

When an option shows only an icon, an image with empty `alt` text, or a color swatch, screen reader users hear "option, 2 of 6" with nothing to tell the choices apart. A group with no name gives no context for the options inside it.

Give each option visible text, or an `aria-label` when it shows only an image. Name each group by pointing `aria-labelledby` at its visible heading.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Gives each option a unique name**

**Reported as:** Group contains duplicate names

Options in the same listbox should have unique accessible names.

When two options share a name, such as two "Springfield" options told apart only by a state shown in a separate column, screen reader users can't tell which one they're selecting. Voice control users can't pick one by name either.

Include the distinguishing text in each name, such as "Springfield, Illinois" and "Springfield, Missouri".

**Severity:** Serious

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

### Set size

The browser counts the options in a listbox when they're all in the DOM. When only part of the set is loaded, set `aria-setsize` on every option to the total number of options, with the same value on each, so assistive technology can report the size of the full list.

**Reports one size for the set**

**Reported as:** Aria-setsize conflicting values

Every option in a listbox must declare the same `aria-setsize`.

When options are loaded in batches and each batch keeps the count known at the time, the total size changes as users move through the list, from "3 of 10" to "4 of 20". Users can't tell which number is right or how much is left.

Write the total size to every option from one source, and update it on all of them when the set changes. When the full size isn't known yet, leave the attribute off.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

**Carries the size on each option**

**Reported as:** Aria-setsize invalid implementation

A listbox should set `aria-setsize` on each option, not on the listbox.

When the count sits only on the listbox, it never reaches assistive technology, which reads the total size from the option that has focus. Users moving through a partly loaded list hear no total size.

Set `aria-setsize` on every option with the same value, along with each option's `aria-posinset`, in the same code that renders the options.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

### Set position

The browser works out each option's position, reported as "3 of 8", when every option is in the DOM. When the listbox loads options as the user scrolls, so only part of the set is present, set `aria-posinset` on each option to its position in the full set. Otherwise, leave it off.

**Fits each position in the set**

**Reported as:** Aria-posinset is larger than aria-setsize

An option's `aria-posinset` must be a whole number from 1 up to its `aria-setsize`.

When positions come from an array index, or from the options currently rendered rather than the full set, screen reader users hear something that can't be true, such as "option 12 of 5", and lose track of how far through the list they are.

Derive the position and the size from the same collection, start positions at 1, and recompute both when options are filtered or reordered.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

**Carries the position on each option**

**Reported as:** Aria-posinset invalid implementation

A listbox should set `aria-posinset` on each option, not on the listbox.

When the attribute sits on the listbox, it has no effect, and the options that need a position have none. Users moving through a partly loaded list get no sense of where they are in the whole.

Move `aria-posinset` onto each option, numbered by its place in the full set, and set `aria-setsize` alongside it.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

### Keyboard navigation orientation

A listbox is vertical by default: the `listbox` role has an implicit `aria-orientation` of `vertical`. A listbox whose options sit in a row sets `aria-orientation="horizontal"` and answers the Left Arrow and Right Arrow keys, so screen reader users know which keys to press.

**Declares the orientation it uses**

**Reported as:** Conflicting aria-orientation

A listbox's `aria-orientation` must match the arrow keys that move focus among its options.

When `aria-orientation` says `horizontal` while the Up Arrow and Down Arrow keys move focus, or the reverse, screen reader users press the keys they were told to use and nothing happens. They conclude the listbox has no keyboard support.

Set `aria-orientation` to `horizontal` when the Left Arrow and Right Arrow keys move focus, and leave it off or set it to `vertical` when the Up Arrow and Down Arrow keys do. Derive the attribute and the key handling from the same state.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Uses a valid aria-orientation value**

**Reported as:** Invalid aria-orientation value

A listbox's `aria-orientation` should be `horizontal` or `vertical`.

When the attribute holds any other value, such as `row` or an empty string, assistive technology ignores it and reports the listbox as vertical. Users of a horizontal listbox are told to use the Up Arrow and Down Arrow keys, which do nothing.

Write one of the two values, in lowercase, chosen to match the keys that move focus. For a vertical listbox, you can leave the attribute off.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

### aria-selected

Each selectable option in a custom listbox reports whether it's selected with one state attribute, usually `aria-selected`, kept in step with the selection. A native `<option>` reports its state through its `selected` property instead.

**Marks which option is selected**

**Reported as:** No selection attributes

Every selectable option in a custom listbox must declare its selection state with `aria-selected`, or with `aria-checked` used the same way on every option.

When selection is shown only by styling, screen reader users hear each option's name with no indication of which one is chosen. They can't tell the current value, or whether their choice took effect.

Set `aria-selected="true"` on each selected option and `"false"` on every other selectable option, from the same state that applies the selected styling. Leave the attribute off an item that can't be selected.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Leaves native state to HTML**

**Reported as:** Avoid aria-checked on native elements

A native `<option>` must report its selection through its `selected` property, without an `aria-checked` attribute.

When `aria-checked` is added to a native option, the ARIA state and the native one are maintained separately and can disagree. Users can be told an option is unchecked while the form submits it as selected.

Remove `aria-checked` from native `<option>` elements. Set the starting selection with the `selected` attribute, and let the `selected` property report the state. Keep ARIA states for options built from generic elements, which have no native state.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Picks one selection state**

**Reported as:** Mixed selection attributes

A listbox should indicate selection with either `aria-selected` or `aria-checked` on its options, not both.

When options carry both attributes, the values can drift apart, so an option can be reported as checked and not selected at the same time. Users can't tell which state reflects their choice.

Choose one attribute and remove the other.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

### Disabled

A listbox, a group, or a single option can be disabled. A native `<select>`, `<optgroup>`, or `<option>` uses the `disabled` attribute, and a custom one uses `aria-disabled="true"`, which on a listbox or group applies to every option inside it. A disabled custom option stays in the arrow-key sequence so screen reader users can find it, but it can't be selected.

**Disables only when role allows**

**Reported as:** Component does not support disabled state

In a listbox, only the listbox, its groups, and its options can declare a disabled state.

When `disabled` or `aria-disabled` sits on a group's heading, on a wrapper around an option, or on the label that names the listbox, assistive technology may drop the state or report it on something users can't operate, while the disabled state isn't reported for the options themselves.

Move the state onto each option that isn't available, or onto the group or listbox when none of its options is.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Disables only elements that support it**

**Reported as:** Element type does not support disabled state

An element in a listbox must carry `disabled` or `aria-disabled` only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native `<button>`.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Avoids conflicting disabled states**

**Reported as:** Conflicting disabled values

A listbox, group, or option must declare its disabled state one way only: the `disabled` attribute on a native `<select>`, `<optgroup>`, or `<option>`, or `aria-disabled` on a custom one.

When a native option carries `aria-disabled` instead of `disabled`, it can still be selected while assistive technology reports it as disabled. When both attributes are set and disagree, assistive technology can report a state the browser doesn't enforce. Either way, screen reader users are told the wrong thing about whether the option is available.

Use `disabled` alone on native elements and `aria-disabled` alone on custom ones, removing it or setting it to `false` when the option is available again.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Uses aria-disabled rather than disabled**

**Reported as:** Element does not support the disabled attribute

A custom listbox, group, or option must convey its disabled state with `aria-disabled`, not the `disabled` attribute.

When `disabled` is set on the `<div>` behind a custom option, the browser ignores it. The option stays in the accessibility tree as an ordinary, available choice, so users are told they can select an option the design means to be unavailable, even when styling grays it out.

Set `aria-disabled="true"` instead, and have the script refuse to select the option while it's set. When the options need no custom presentation, a native `<select>` handles the disabled state itself.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

### Forbidden interactive children

Options and groups contain no interactive elements. The `option` role makes its content presentational, and the listbox's keyboard model has no way to reach a control inside an option. A link or button placed there can't be used from the keyboard or by assistive technology. When each item needs its own controls, use a data grid instead of a listbox.

**Avoids nested interactives**

**Reported as:** Forbidden interactive children; Nested interactive elements

A listbox's options and groups must not contain interactive elements, such as a link, a button, or a checkbox.

When an option holds a control, such as a remove button beside each name, assistive technology may drop the inner control's role or expose only the option. Screen reader users hear one control where two exist, and a click or key press has two plausible targets.

Move the action out of the listbox, for example into a toolbar that acts on the selected options, or build the list as a grid when every item needs its own controls.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

## Relationships

A listbox owns its options. They're its DOM descendants, either directly or inside groups, and each group owns the options it contains. Assistive technology builds the listbox's structure from this nesting, so the order of options in the DOM is the order users meet them.

A listbox can also be the popup of a combobox, which points at it with `aria-controls` and manages focus for it. [Combobox](https://knowledge.evinced.com/web/ui-patterns/combobox) covers that relationship.

### aria-owns

A listbox has no need for `aria-owns` when its options and groups are nested inside it in the DOM. When options have to be rendered elsewhere, `aria-owns` on the listbox or a group can claim them, but only in the accessibility tree.

**Avoids aria-owns**

**Reported as:** Avoid aria-owns

**General check.** Evinced checks that the listbox, its groups, and its options don't use `aria-owns` to claim elements elsewhere in the document as their children. This check runs on every UI pattern, not only on listboxes.

A listbox and its groups should hold their options in the DOM rather than own them with `aria-owns`, and an option should own nothing.

When options rendered elsewhere are owned, assistive technology places them after the listbox's own options, and one that doesn't honor the attribute reports them outside the listbox, so screen reader users hear options in a different order from the one the arrow keys follow. When an option owns content, that content becomes presentational, so it can vanish, be folded into the option's name, or be read twice.

Render the options inside the listbox or its groups, or portal the whole listbox. When some options must be owned, list every option in `aria-owns` in the order the arrow keys move through them.

**Owns only conforming roles**

**Reported as:** Invalid aria-owns values

**General check.** Evinced checks that every element the listbox or a group references in `aria-owns` has a role it may own. This check runs on several UI patterns.

When a listbox uses `aria-owns`, every element it references should have the `option` or `group` role, and a group should reference only options.

When an owned element has another role, the listbox's structure no longer adds up: the option count and positions screen reader users hear come out wrong, and the arrow keys can reach items the listbox doesn't handle.

Reference only options and groups, each from a single container. Better still, move them into the listbox in the DOM and remove `aria-owns`.

## Operation

With a pointer, clicking an option selects it. In a single-select listbox, that replaces the previous selection. In a multi-select listbox, it toggles the option and leaves the others as they are.

With a keyboard, the Tab key moves focus to the listbox as a single stop in the tab order, landing on the selected option or, when none is selected, on the first. The arrow keys move focus among the options, and Space selects the focused option.

Focus and selection are separate. Moving focus doesn't change the selection unless a single-select listbox is built so that selection follows focus. That design suits a list where selecting has no delay or side effect.

Focus is managed in one of two ways, both described in [Keyboard Navigation Inside Components](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#keyboardnavigationinsidecomponents). With `aria-activedescendant`, the listbox keeps keyboard focus and the attribute identifies the focused option. With a roving tabindex, the focused option holds `tabindex="0"` and the others `tabindex="-1"`. A listbox that's a combobox popup leaves focus on the combobox, which points its own `aria-activedescendant` at the focused option.

The following table shows the keys for a vertical listbox. In a horizontal listbox, the Right Arrow and Left Arrow keys take the place of the Down Arrow and Up Arrow keys.

| Key | Function |
| :-- | :-- |
| Down Arrow | Moves focus to the next option or, from the last, to the first |
| Up Arrow | Moves focus to the previous option or, from the first, to the last |
| Home | Moves focus to the first option |
| End | Moves focus to the last option |
| Space | Selects the focused option, or toggles it in a multi-select listbox |
| Typed characters (recommended) | Moves focus to the next option whose name starts with the characters typed |

### Focus sequence

A listbox is a single stop in the tab order. Either the listbox holds `tabindex="0"` and identifies the focused option with `aria-activedescendant`, as in the [Custom Listbox With Groups](https://knowledge.evinced.com/web/ui-patterns/listbox#custom-listbox-with-groups) example, or one option holds `tabindex="0"` and the others `tabindex="-1"`. A listbox that's the popup of a combobox has no tab stop of its own: focus stays on the combobox, as [Combobox › Focus Sequence](https://knowledge.evinced.com/web/ui-patterns/combobox#focus-sequence) describes.

The following example shows the roving tabindex method, with the tab stop on the selected option.

```html
<span id="fruit-label">Fruit</span>
<div role="listbox" aria-labelledby="fruit-label">
  <div role="option" id="apple" tabindex="-1" aria-selected="false">Apple</div>
  <div role="option" id="banana" tabindex="0" aria-selected="true">Banana</div>
  <div role="option" id="orange" tabindex="-1" aria-selected="false">Orange</div>
</div>
```

**Keeps aria-activedescendant valid**

**Reported as:** Missing active descendant

When a listbox manages focus with `aria-activedescendant`, the attribute must hold the `id` of an option in the listbox whenever the listbox has focus.

When the attribute is missing, or points at an `id` that no longer exists, screen reader users hear the listbox's name and role but no option. They can't tell where they are in the list or what Space would select.

Give every option a unique `id`, and set `aria-activedescendant` each time the listbox receives focus. Set it to an empty string when the listbox has no options.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

**Reachable with the Tab key**

**Reported as:** Composite not in focus sequence

A listbox must have one element in the tab order, either the listbox itself or one of its options.

When the listbox has no `tabindex` and every option has `tabindex="-1"`, or none has a `tabindex` at all, the Tab key passes over the listbox. Keyboard users can't reach it, and the arrow keys only work once something inside it has focus.

Give the listbox `tabindex="0"` and use `aria-activedescendant`, or give one option `tabindex="0"` and the rest `tabindex="-1"`. Set the tab stop when the listbox first renders.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Lands on the selected option**

**Reported as:** Listbox unpredictable focus

When focus enters a listbox, it must land on the selected option, or on the first option when none is selected. In a multi-select listbox, it lands on the first selected option.

When focus always starts at the top, screen reader users hear the first option as though it were the current value. In a long list, the selected option can be many key presses away.

Set the focused option from the current selection each time the listbox receives focus, and scroll it into view. With a roving tabindex, move `tabindex="0"` onto the selected option before focus arrives.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Uses one focus management method**

**Reported as:** Conflicting focus management methods

A listbox should put either itself or one of its options in the tab order, not both.

When the listbox has `tabindex="0"` and its options are focusable too, the Tab key stops on the listbox and again on an option. The same option is reported twice, by two methods, and the arrow keys work from one stop and not the other.

For `aria-activedescendant`, keep the listbox in the tab order and remove `tabindex` from the options or set it to `-1`. For a roving tabindex, leave the listbox out of the tab order.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

**Gives its options a single tab stop**

**Reported as:** Redundant focusable children

Only one option in a listbox should be in the tab order, with the arrow keys reaching the rest.

When every option has `tabindex="0"`, the Tab key stops on each one, so users press Tab through the whole list to leave it, and the listbox reads as a series of separate controls.

Give one option `tabindex="0"` and the rest `tabindex="-1"`, and move the `tabindex="0"` as focus moves, so Tab returns users to the option they were last on.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### Context change

Selecting an option changes only the listbox's value. Anything more, such as submitting the form, loading another page, or moving focus, waits for an explicit control such as a submit button. This matters most in a single-select listbox where selection follows focus: the arrow keys select each option they reach, so every step through the list is a change.

**Keeps context when a value changes**

**Reported as:** Unexpected context change on input

Selecting an option in a listbox must not change the context unless users are told beforehand that it will.

When selecting an option loads another page or moves focus, screen reader and screen magnifier users may not notice that the page changed. In a listbox where selection follows focus, keyboard users can't get past the first option they arrow to. A form that submits partway through can discard what users hadn't finished entering.

Update the page in place and leave focus in the listbox. Start submission or navigation from an explicit control such as an Apply button, or, when the change of context is intended, say so in text that comes before the listbox.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [3.2.2 On Input](https://www.w3.org/TR/WCAG22/#on-input) (A) | Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component. |
| EN 301 549 | [9.3.2.2 On Input](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.22(n)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d22) | When electronic forms are designed to be completed on-line, the form shall allow people using assistive technology to access the information, field elements, and functionality required for completion and submission of the form, including all directions and cues. |
| Section 508 | [1194.21(l)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When electronic forms are used, the form shall allow people using assistive technology to access the information, field elements, and functionality required for completion and submission of the form, including all directions and cues. |

### Keyboard navigation

The arrow keys move focus from one option to the next, wrapping at either end, and Home and End move it to the first and last option. The script in the [Custom Listbox With Groups](https://knowledge.evinced.com/web/ui-patterns/listbox#custom-listbox-with-groups) example handles each of these keys. In a listbox that's a combobox popup, the combobox handles them while keeping focus.

**Keeps aria-activedescendant valid**

**Reported as:** Missing active descendant

When a listbox manages focus with `aria-activedescendant`, the attribute must change to the newly focused option each time the arrow keys, Home, or End move focus.

When the attribute keeps the value it had at setup, the visible highlight moves, but screen reader users hear the old option, or none. They select an option they aren't on.

Update `aria-activedescendant` in the same step that moves the highlight, and derive both from one piece of state so they can't disagree. Give every option a unique `id` for the attribute to reference.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

**Moves focus with the arrow keys**

**Reported as:** Focus not updated with arrow keys

The Down Arrow and Up Arrow keys must move focus to the next and previous option.

When the listbox answers only clicks, an arrow key scrolls the page and focus stays where it was. Keyboard users can't reach any option after the first, even though the whole list is on screen.

Handle the arrow keys on the listbox, move focus one option per press with `aria-activedescendant` or a roving tabindex, and call `preventDefault` so the page doesn't scroll.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Keeps focus on the control**

**Reported as:** Combobox not focused after action

When a listbox is the popup of a combobox, moving through its options must leave keyboard focus on the combobox.

When the key handler calls `focus()` on each option, typing no longer reaches the combobox's input. Screen reader users hear a bare option instead of the field and its value, and can't tell whether their typed text survived.

Keep focus on the combobox and set its `aria-activedescendant` to the `id` of the active option on each arrow, Home, and End key press.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence) (A) | When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined. |
| EN 301 549 | [9.1.3.2 Meaningful Sequence](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

**Moves focus with Home and End**

**Reported as:** Focus not updated with Home or End keys

The Home key must move focus to the first option and the End key to the last.

When only the arrow keys are handled, Home and End scroll the page instead, and reaching the far end of the list takes one key press per option, each announced by a screen reader. The focused option can also scroll out of view.

Handle Home and End on the listbox, move focus the same way the arrow keys do, and call `preventDefault` so the page doesn't scroll.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Wraps focus at the ends**

**Reported as:** Arrow key navigation loop failed

From the last option, the Down Arrow key should move focus to the first, and from the first, the Up Arrow key should move it to the last.

When focus stops at either end, a key press does nothing, which looks the same as a listbox whose keyboard support has stopped working. Users press again rather than turning around.

When focus is on the last option and the Down Arrow key is pressed, move focus to the first option, and mirror that for the Up Arrow key. Keep focus inside the listbox.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

**Matches arrow keys to orientation**

**Reported as:** Arrow key navigation failed

**Sanity check.** Evinced checks that the arrow keys matching the listbox's layout move focus among its options. This check runs on several UI patterns.

A listbox's arrow keys should match its layout: the Up Arrow and Down Arrow keys for a vertical listbox, and the Left Arrow and Right Arrow keys for a horizontal one.

When a row of options answers only the Up Arrow and Down Arrow keys, the keys that match what's on screen do nothing, and users conclude the listbox has no keyboard support.

Handle the pair of keys that matches the layout and the `aria-orientation` value, and leave the other pair to scroll the page.

**Manages focus across every option**

**Reported as:** Skipping composite arrow key navigation

**Sanity check.** Evinced checks that the arrow keys reach every option in the listbox in turn, skipping none. This check runs on several UI patterns.

Every option in a listbox should be able to take focus in turn, not just the first few.

When focus management covers only some options, such as a roving tabindex applied to the options rendered first, the arrow keys stall partway through the list. Users can't tell whether they've reached the end or hit a broken option, and every option past the gap is out of reach.

Apply one focus method to every option, and generate it from the same list that renders the options so an option added later isn't left out.

### Unreachable group

The selected option in a listbox can always take focus. With a roving tabindex, it usually holds the listbox's only tab stop, so the Tab key reaches the listbox through it.

**Keeps the selected option reachable**

**Reported as:** Unreachable group

The selected option in a listbox must be able to take keyboard focus.

When the selected option carries `tabindex="-1"` with no other option holding `tabindex="0"`, or it's disabled while still shown as selected, the Tab key passes over the listbox. Keyboard users can't reach any option, including the one plainly marked as chosen.

Give the selected option `tabindex="0"` and move it as the selection moves. When the selected option has to be disabled, put the tab stop on another option.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

### Multi select listboxes

A multi-select listbox follows one of the two keyboard models APG describes. The recommended model needs no modifier keys: Space toggles the focused option, and the arrow keys move focus without changing the selection. The other model uses Shift and Control to extend the selection, and an arrow key pressed alone moves the selection with focus.

The recommended model uses the following keys. All but Space are optional.

| Key | Function |
| :-- | :-- |
| Space | Toggles the selected state of the focused option |
| Shift + Down Arrow | Moves focus to the next option and toggles its selected state |
| Shift + Up Arrow | Moves focus to the previous option and toggles its selected state |
| Shift + Space | Selects every option from the most recently selected one to the focused one |
| Control + Shift + Home | Selects the focused option and every option before it, and may move focus to the first option |
| Control + Shift + End | Selects the focused option and every option after it, and may move focus to the last option |
| Control + A | Selects every option, or unselects them all when all are already selected |

**Selects several without modifier keys**

**Reported as:** Possibly unsupported selection model

**Sanity check.** Evinced checks that a multi-select listbox lets users select more than one option without holding a modifier key.

A multi-select listbox should let users select several options without holding a modifier key, or implement the modifier-key model completely.

When Shift or Control is the only way to extend the selection and a plain arrow key replaces it, people who can't hold two keys at once can't select more than one option. Keyboard users who move through the list lose their earlier choices without being told.

Make Space toggle the focused option without changing the others. If the modifier-key model is required, also make Control with the arrow keys move focus without changing the selection.

### Selected options

A single-select listbox has at most one selected option. A listbox that allows more than one declares it with `aria-multiselectable="true"`, or with the `multiple` attribute on a native `<select>`, and each selected option reports its own state.

The following example shows a multi-select listbox with two options selected.

```html
<span id="fruit-label">Fruit</span>
<div
  role="listbox"
  id="fruit"
  tabindex="0"
  aria-labelledby="fruit-label"
  aria-multiselectable="true">
  <div role="option" id="apple" aria-selected="true">Apple</div>
  <div role="option" id="banana" aria-selected="true">Banana</div>
  <div role="option" id="orange" aria-selected="false">Orange</div>
</div>
```

**Acts on Space when focused**

**Reported as:** Spacebar does not trigger selection

Pressing Space on the focused option must select it, or toggle its selected state in a multi-select listbox.

When the listbox handles only clicks or the Enter key, or lets Space scroll the page, keyboard users get no selection and no error. Most conclude the option can't be chosen.

Handle Space on the listbox, run the same code a click runs, and call `preventDefault` so the page doesn't scroll. Update `aria-selected` in the same step.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Declares multiple selection**

**Reported as:** Aria-multiselectable attribute required

A listbox that allows more than one selected option must set `aria-multiselectable="true"`.

The attribute defaults to `false`, so when it's missing, screen reader users are told only one option can be chosen. They select one and move on, or hear several options reported as selected and take it for a fault.

Set `aria-multiselectable="true"` on the element with the `listbox` role, or add the `multiple` attribute to a native `<select>`. Keep `aria-selected` on each option, `true` on the chosen ones and `false` on the rest.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### Event listener type

When script in a listbox responds to keys, it listens for `keydown` or `keyup`. The `keypress` event is deprecated, and browsers don't fire it for many keys, including the arrow keys, Home, End and Escape.

**Avoids the keypress event**

**Reported as:** Deprecated keypress listener

A listbox's key handling should use `keydown` or `keyup`, not `keypress`.

When a handler listens for `keypress`, keys the browser doesn't send through that event go unanswered, and keyboard users find the listbox ignoring keys it's meant to respond to.

Replace each `keypress` listener with a `keydown` listener, and read the key from `event.key`.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

## FAQ

**Which WCAG success criteria do the listbox issues relate to?**

Most relate to 4.1.2 Name, Role, Value: the listbox, group, and option roles, each option's name, reporting which options are selected, how a disabled state is declared, and keeping interactive elements out of options.

Naming the listbox, containing options with the required role, the set size and positions, `aria-activedescendant`, a single tab stop, and declaring multiple selection relate to 1.3.1 Info and Relationships. Keeping focus on a combobox while users move through its popup relates to 1.3.2 Meaningful Sequence, and selecting an option without changing the context relates to 3.2.2 On Input.

Reaching the listbox, landing on the selected option, moving focus with the arrow keys, Home, and End, matching the orientation, selecting with Space, and keeping at least one option available relate to 2.1.1 Keyboard.

Distinct option names, setting the size and position on each option, a valid `aria-orientation` value, one selection attribute, and wrapping focus at the ends map to no WCAG success criterion and are best practices.

**Why are some listbox issues marked as Critical and others as Minor?**

Severity reflects how much an issue gets in users' way. Critical issues stop users outright: a listbox with no role, options with no name or selected state, no option available, or a listbox keyboard users can't reach or move through.

Serious issues confuse users though tasks are still possible, such as duplicate option names, an orientation that doesn't match the keys, a wrong disabled state, controls inside options, focus that doesn't land on the selected option, Space that doesn't select, or a selection that changes the context.

An unnamed listbox, a set size or position that can't be true, a tab stop on more than one element, Home and End that don't move focus, or a missing `aria-multiselectable` is Moderate. Setting the size or position on the listbox, an invalid `aria-orientation` value, mixing selection attributes, or focus that stops at the ends is Minor.

The `aria-owns` checks and the checks on where the role sits, arrow-key focus, and the multi-select keyboard model carry no severity: Evinced reports them as general and sanity checks.

## Related Patterns

-   [Checkbox](https://knowledge.evinced.com/web/ui-patterns/checkbox): marks any number of options as chosen
-   [Combobox](https://knowledge.evinced.com/web/ui-patterns/combobox): a control that shows one value and opens a list, often a listbox, to change it
-   [Data Grid](https://knowledge.evinced.com/web/ui-patterns/data-grid): a grid of interactive cells, for lists whose items need their own controls
-   [Menu](https://knowledge.evinced.com/web/ui-patterns/menu): a list of commands that run when chosen
-   [Menu Button](https://knowledge.evinced.com/web/ui-patterns/menu-button): a button that opens a menu of commands
-   [Radio Group](https://knowledge.evinced.com/web/ui-patterns/radio-group): a single choice from a short set of options, all shown at once

## Recommended Reading

-   [Listbox Pattern | W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)
-   [ARIA: listbox role | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role)
-   [ARIA: option role | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role)
-   [ARIA: group role | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role)
