Listbox

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

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"));

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

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

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

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

Reported as: Incorrect root element

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Reported as: Avoid aria-owns

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.

Reported as: Invalid aria-owns values

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.

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

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

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

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

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

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

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

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

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

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

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

Reported as: Arrow key navigation failed

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.

Reported as: Skipping composite arrow key navigation

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.

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

Reported as: Possibly unsupported selection model

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.

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

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

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

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.

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.