Combobox

Reported as: Empty data-list

A combobox must contain at least one option.

When a <select>, the <datalist> an input references, or a custom combobox's listbox has no options, users reach a field presented as a set of choices and find nothing to choose. Screen reader users get no announcement explaining the empty list, and a required field can't be completed.

Fill the list before the combobox is offered, and keep the field disabled until options that load separately arrive. When a set can be empty, say so beside the field, and handle a failed request as its own case rather than as an empty list.

Severity: Critical

Reported as: No active options

A combobox's popup must have at least one option that isn't disabled.

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

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

Severity: Critical

Reported as: No group members with required role

A combobox's listbox popup, and each group in it, must contain elements with the option role.

When the popup's children are generic elements, or extra wrappers sit between the listbox and its options, assistive technology finds no options to report. The combobox's aria-activedescendant then points at elements that aren't options, and screen reader users hear the highlighted text with no role, 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: Element has incorrect role

A custom combobox must carry role="combobox", and its popup must carry the role of the widget it is, such as listbox.

When an input that opens suggestions has no role, assistive technology reports a plain text field, so users type without knowing a list of options exists or that the arrow keys reach it. When the popup has no role, its options aren't reported as choices at all.

Add role="combobox" to the input and role="listbox" to the popup, or use a <select> or an <input> with a <datalist>, which carry the roles natively.

Severity: Critical

Reported as: Incorrect root element

A custom combobox should carry the combobox role on the element that receives focus, not on a wrapper around it.

When the role sits on a container around the input, as ARIA 1.1 prescribed, assistive technology reports the focused input without it. Users land in a text field with no word that it has a popup, and the combobox's aria-expanded and aria-activedescendant describe an element that never has focus.

Put the role, the accessible name, aria-expanded, aria-controls, and aria-activedescendant on the input, and keep any layout wrapper free of roles.

Reported as: Missing contextual labeling

A combobox must have an accessible name that says which choice it offers.

When the combobox has no name, screen reader users hear "combobox" and a value with nothing to say what the value is for.

Associate a <label> with the combobox element, or point its aria-labelledby at the visible label. Use aria-label only when there's no visible label.

Severity: Critical

Reported as: Missing contextual labeling

A combobox's listbox popup must have an accessible name that says which choice it offers.

When the popup has no name, assistive technology that reports the popup identifies it only as a listbox, so users can't tell which field's choices they're hearing.

Point the popup's aria-labelledby at the combobox's label, so the field and its popup describe the same choice.

Severity: Moderate

Reported as: Group members missing accessible names

Every option in a combobox's popup, and every group of options, must have an accessible name.

When an option shows only an icon or a color swatch, screen reader users moving through the popup 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, and name each group with aria-labelledby pointing at its visible heading.

Severity: Critical

Reported as: Group contains duplicate names

Options in a combobox's popup should have unique accessible names.

When two suggestions share a name, such as two "Springfield" entries told apart only by a state shown in another column, screen reader users can't tell which one they're about to choose, and the value in the field doesn't say which one they chose.

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

Severity: Serious

Reported as: Invalid aria-haspopup value

A combobox's aria-haspopup should name the role of its popup.

When the value isn't one ARIA defines, assistive technology ignores it and users get no warning of what opens. When it names the wrong kind of popup, such as true or menu for a listbox, or listbox for a dialog, users prepare for the wrong interaction and press keys the popup doesn't answer.

Leave the attribute off for a listbox popup, or set it to listbox, the combobox role's default. For any other popup, set grid, tree, or dialog to match the popup's role.

Severity: Minor

Reported as: Unexpected aria-haspopup value

A combobox's aria-haspopup value must name the kind of popup it opens.

When the value is one ARIA allows but doesn't match the popup, such as menu on a combobox whose popup is a listbox, assistive technology tells users to expect a different kind of popup, and they bring the wrong keys and expectations to it.

Set aria-haspopup to the popup's role: listbox, grid, tree or dialog. A combobox's default is listbox, so the attribute can be left off for a listbox popup.

Severity: Minor

Reported as: Combobox list is not filtered

When a combobox's aria-autocomplete value is list or both, the options in its popup must narrow as users type.

When the list stays the same, or non-matching options are hidden with CSS while staying in the accessibility tree, users are told typing will narrow the choices, type, and still get the whole list. Screen reader users hear twenty options while the screen shows two.

Remove the non-matching options from the popup, or hide them with hidden, and point aria-activedescendant at the first match. Derive the declaration and the filtering from the same setting, so a combobox that doesn't filter declares none.

Severity: Serious

Reported as: Combobox redundant aria-autocomplete

A combobox must carry aria-autocomplete only on an element that accepts text input.

When a select-only combobox, its popup, or the options in the popup carry the attribute, assistive technology describes something that should accept typing. Users type into a control that ignores them and conclude it's broken, or are told the popup and its options are inputs, which contradicts their roles.

Set aria-autocomplete on the editable combobox element alone. Remove it from a select-only combobox and from everything inside the popup.

Severity: Serious

Reported as: Aria-autocomplete invalid value

A combobox's aria-autocomplete should be list, inline, both, or none.

When the value is anything else, such as true, or on and off borrowed from HTML's autocomplete attribute, assistive technology ignores it and treats the combobox as offering no predictions. Users aren't told typing narrows the list, so they read through it instead.

Choose the value that matches the behavior: list when typing narrows the popup, inline when the field completes the entry, both when it does the two, and none when the options don't depend on what's typed.

Severity: Minor

Reported as: Combobox is missing aria-autocomplete attribute

An editable combobox that suggests values as users type should declare it with aria-autocomplete.

When the attribute is missing, the combobox reads as one whose options users only pick from. Screen reader users don't know typing is the fast way through a long list, and when options appear and disappear as they type, the list seems to be losing content rather than filtering it.

Set aria-autocomplete on the combobox element to list, inline, or both, whichever matches what typing does. Leave it off a combobox whose suggestions don't depend on what's typed, such as a list of recent searches.

Severity: Minor

Reported as: Aria-setsize conflicting values

Every option in a combobox's popup must declare the same aria-setsize.

When results load in batches and each batch keeps the count known at the time, or filtering updates the count on some options and not others, the total changes as users move through the popup, from "3 of 10" to "4 of 20". Users can't tell which number is right or how many matches are left.

Write the total 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, set aria-setsize="-1" on every option.

Severity: Moderate

Reported as: Aria-setsize invalid implementation

A combobox's popup should set aria-setsize on each option, not on the listbox or the combobox.

When the count sits only on the listbox or the combobox, it never reaches assistive technology, which reads the total from the active option. Users moving through a partly loaded popup hear no total.

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 before filtering rather than the ones in the popup, screen reader users hear something that can't be true, such as "option 12 of 5", and lose track of how far through the matches they are.

Derive the position and the size from the same collection, start positions at 1, and recompute both each time typing filters the options.

Severity: Moderate

Reported as: Aria-posinset invalid implementation

A combobox's popup should set aria-posinset on each option, not on the listbox or the combobox.

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

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

The aria-orientation of a combobox's popup must match the arrow keys that move through its options.

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

Leave aria-orientation off, or set it to vertical, when the Down Arrow and Up Arrow keys move through the options, and set it to horizontal only when the Left Arrow and Right Arrow keys do. Derive the attribute and the key handling from the same state.

Severity: Serious

Reported as: Invalid aria-orientation value

The aria-orientation of a combobox's popup 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 popup as vertical. Assistive technology then treats a horizontal popup as vertical, so what it reports doesn't match the keys that work.

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

Severity: Minor

Reported as: Conflicting aria-expanded value

A combobox's aria-expanded value must match whether its popup is visible.

When the value is set by the key press or click that was expected to open the popup, rather than by the popup's own state, the two fall out of step the first time the popup closes some other way, such as when typing leaves no match or users click elsewhere. Screen reader users are told options are available that aren't there, or that nothing is open while the list covers the page.

Derive aria-expanded from the same state that shows the popup, and update it on every route in and out: Escape, a selection, the combobox losing focus, and a filter that empties the list.

Severity: Critical

Reported as: Aria-expanded value did not change

A combobox's aria-expanded value must change every time its popup opens or closes.

When the value stays as it was, screen reader users hear the old state after they type or press the Down Arrow key, so they can't tell whether suggestions appeared. They may press again and close the popup they just opened.

Set the attribute in the code that shows and hides the popup, so every path that opens or closes it updates the state, including a programmatic close.

Severity: Serious

Reported as: Missing aria-expanded attribute

A custom combobox must carry aria-expanded.

When the attribute is missing, assistive technology has no state to report. Screen reader users aren't told whether the popup is open, and after typing or pressing the Down Arrow key they can't tell whether anything appeared.

Add aria-expanded="false" to the combobox element in its first render, and set it to true while the popup is showing. Put it on the element with the combobox role, not on the popup or a wrapper.

Severity: Serious

Reported as: Combobox selection with Enter key failed

Pressing Enter while a combobox's popup is open must accept the active option: put its value in the combobox, mark it selected, and close the popup.

When Enter isn't handled, or a form's submit consumes it first, keyboard users can reach the value they want and not take it. Inside a form, a press meant as a choice sends the form with the old value.

Handle Enter on the combobox while the popup is open, run the same code a pointer selection runs, and call preventDefault so the form isn't submitted. When the popup is closed, leave Enter to the form.

Severity: Critical

Reported as: No selection attributes

Every selectable option in a custom combobox's popup must declare whether it's selected.

When the options carry no selection state at all, screen reader users moving through the popup get no indication of which option holds the current value, or whether choosing one took effect.

Set aria-selected="false" on every selectable option when the popup is rendered, and true on the option holding the combobox's value.

Severity: Critical

Reported as: Avoid aria-checked on native elements

A native <option> in a <select> or <datalist> 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 kept separately and can disagree. Users can be told an option is unchecked while the form submits it as the value.

Remove aria-checked from native <option> elements. Set the starting selection with the selected attribute, and let the selected property report the state.

Severity: Serious

Reported as: Missing selection indication

The option holding a combobox's value must carry aria-selected="true".

When the current value is marked only with styling, or aria-selected sits on an option other than the one whose value the combobox shows, screen reader users who reopen the popup to check or change their choice hear every option as equally available. They have to remember what they chose.

Set aria-selected to true on the option matching the combobox's value and false on the others, from the value itself, so it's still correct when the popup reopens.

Severity: Minor

Reported as: Mixed selection attributes

The options in a combobox's popup should indicate selection with aria-selected alone, not alongside aria-checked.

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 the combobox's value.

Remove aria-checked from the options and keep aria-selected.

Severity: Minor

Reported as: Component does not support disabled state

In a combobox, only the combobox element itself, and the options and groups in its popup, can declare a disabled state.

When disabled or aria-disabled sits on a wrapper around the input, on its label, or on the dropdown icon, assistive technology may drop the state or report it on something users can't operate, while the disabled state isn't reported for the combobox itself.

Move the state onto the element with the combobox role, or onto each option that isn't available.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a combobox 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 combobox must declare its disabled state one way only: the disabled attribute on an <input> or <select>, or aria-disabled on a custom combobox.

When an <input> or <select> carries aria-disabled instead of disabled, it stays operable 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 they can use the field.

Use disabled alone on an <input> or <select>, and aria-disabled alone on a custom combobox, removing it or setting it to false when the field is available again.

Severity: Serious

Reported as: Element does not support the disabled attribute

A custom combobox built from an element that doesn't support the disabled attribute must convey its disabled state with aria-disabled.

When disabled is set on a <div> with the combobox role, the browser ignores it. The combobox stays in the accessibility tree as an ordinary, available field, so users are told they can use it, even while styling grays it out.

Set aria-disabled="true" instead, and have the script refuse to open the popup or change the value while it's set.

Severity: Serious

Reported as: Combobox options redundant ARIA attributes

Each option in a combobox's popup must declare its selected state with one attribute, and no option should restate what the popup already conveys.

When options carry both aria-selected and aria-checked, nothing settles which state users are told, so the same popup can report different selections to two people. When every option carries a hand-written aria-posinset and aria-setsize, filtering leaves the numbers wrong, and users hear "3 of 12" from a list of four.

Use aria-selected alone on the options. Leave aria-posinset and aria-setsize off when every option is in the DOM, and don't add role="option" to a native <option>.

Severity: Serious

Reported as: Combobox redundant ARIA attributes

A combobox should not declare attributes its role already settles.

An explicit aria-haspopup="listbox" is valid, but it's one more value to keep in step with the popup. Change the popup to a grid, and a leftover listbox tells users to expect the wrong kind of popup. The same goes for referencing the popup with aria-owns as well as aria-controls.

Reference the popup with aria-controls alone, update aria-haspopup whenever the popup's role changes, and derive every remaining attribute from the state that drives the behavior.

Severity: Minor

Reported as: Forbidden interactive children; Nested interactive elements

The options and groups in a combobox's popup must not contain interactive elements, such as a link, a button, or a checkbox.

When an option holds a control, such as a button that removes a saved search from the suggestions, 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 popup, for example to a key users press on the active option, described next to the combobox, or to a separate list of saved searches.

Severity: Serious

Reported as: Aria-controls has multiple targets

A combobox's aria-controls attribute should name one element: its popup.

When it lists several ids, the combobox claims to drive several separate elements, and assistive technology that offers to move users to the controlled content has to pick one or offer none.

Point aria-controls at the element with the popup's role. When the popup needs other elements beside it, such as a status message, put them inside the popup's container or reference them with aria-describedby.

Severity: Minor

Reported as: Invalid aria-controls reference

A combobox's aria-controls attribute must name an element that exists on the page.

When the id matches nothing, because the popup was renamed, replaced, or not rendered yet, the reference fails quietly. Assistive technology finds no popup to relate to the combobox, so it can't tell users where the options are, and the markup still looks correct to anyone reading it.

Generate the popup's id and the aria-controls value from one source. When the popup exists only while it's open, add the attribute when the popup appears and remove it when the popup is destroyed.

Severity: Minor

Reported as: Missing aria-controls attribute

A custom combobox must identify its popup with aria-controls.

When the attribute is missing, nothing in the markup connects the combobox to the options it offers, so assistive technology that uses the relationship can't tell users where the options are. The combobox's aria-activedescendant then points into an element it has no stated relationship with.

Add aria-controls to the combobox element and set it to the popup's unique id. An <input> with a list attribute already states the relationship and doesn't need it.

Severity: Minor

Reported as: Avoid aria-owns

A combobox should reference its popup with aria-controls rather than own it with aria-owns, and the popup should hold its options in the DOM.

When a combobox owns its popup, alone or beside an aria-controls naming the same element, the listbox is reported as part of the input rather than as the separate popup it is. Support for each attribute varies, so two screen reader users can get different structures from the same combobox.

Remove aria-owns and reference the popup's id with aria-controls alone, leaving the popup where it is in the DOM and its options inside it.

Reported as: Invalid aria-owns values

When a combobox's listbox popup 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 popup's structure no longer adds up: the option count and positions screen reader users hear come out wrong, and aria-activedescendant can point at something that isn't an option.

Reference only options and groups. Better still, move them into the popup in the DOM and remove aria-owns.

Reported as: Keyboard accessible; Composite not in focus sequence

A combobox must be reachable with the Tab key.

When the combobox is a generic element with the combobox role and no tabindex, or neither the combobox nor anything in its popup is in the tab order, keyboard users can't reach it. People who navigate without a pointer can't set the value at all, however correct its role and name are.

Build the combobox from an <input> or a <select>, which are focusable already. When a select-only combobox has to be a generic element, give it tabindex="0".

Severity: Critical

Reported as: Missing active descendant

While a combobox's popup is open, its aria-activedescendant must hold the id of the active option, and be empty when no option is active.

When the attribute points at an option that filtering has removed, or keeps the value it was first given as the arrow keys move, screen reader users hear the wrong option or none. Users choose an option they aren't on, or can't tell where they are in the list.

Give every option a unique id, and update the attribute each time the active option changes: on an arrow key, Home, or End, on hover, and when filtering replaces the options. Clear it when the popup closes.

Severity: Critical

Reported as: Focus lost during combobox edit

Keyboard focus must remain on an editable combobox while users type into it.

When each keystroke re-renders the component and replaces the input element, or a blur handler moves focus when the popup changes, focus drops to the page partway through a word. The rest of what users type goes nowhere, and screen reader users get no announcement that focus has gone.

Keep the same input element across re-renders and update its value and attributes in place. Render the popup outside the input's subtree, and don't move focus in response to input events.

Severity: Serious

Reported as: Listbox unpredictable focus

When a combobox's popup opens, the active option must be the one holding the combobox's value, or the first option when there's no value.

When the active position always starts at the top, screen reader users hear the first option as if it were the current value. Users reopening the popup to change their choice lose their place, and in a long list the selected option can be many key presses away.

Set aria-activedescendant from the current value each time the popup opens, and scroll that option into view. Fall back to the first option only when nothing is selected.

Severity: Serious

Reported as: Redundant focusable popup

A combobox's popup must stay out of the tab order.

When the popup's container carries tabindex="0", often added so script can focus it, the Tab key stops on a list that holds no value of its own. Users pressing Tab to leave the combobox land inside its popup instead, and when leaving closes the popup, focus ends up somewhere they didn't choose.

Remove the popup's tabindex, or set it to -1, keep focus on the combobox, and report the active option with aria-activedescendant.

Severity: Moderate

Reported as: Conflicting focus management methods; Redundant focusable children

The options in a combobox's popup must stay out of the tab order while the combobox keeps focus.

When the options are native buttons or links, or carry tabindex="0", the Tab key stops on each one after the combobox. The same option is reported once by aria-activedescendant and again when it takes focus, and users have to press Tab through every suggestion to leave the widget.

Build the options from generic elements with the option role and no tabindex, or set tabindex="-1" on each one, and move among them only by updating the combobox's aria-activedescendant.

Severity: Moderate

Reported as: Unexpected context change on input

Setting a combobox's value must not change the context unless users are told beforehand that it will.

When a change handler loads a page as soon as the value changes, keyboard users who step through a collapsed <select> with the arrow keys are taken away at the first option they reach. Screen reader and screen magnifier users may not notice that the page changed, and a form that submits partway through can discard what users hadn't finished entering.

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

Severity: Serious

Reported as: Missing active descendant

The combobox's aria-activedescendant must change to the newly highlighted option each time a key moves the highlight.

When the attribute keeps the value it had when the popup opened, the visible highlight moves, but screen reader users hear the old option, or none. They accept 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

While the popup is open, the Down Arrow and Up Arrow keys must move the highlight to the next and previous option.

When the popup answers only clicks, an arrow key moves the caret or scrolls the page, and the highlight stays where it was. Keyboard users can't reach any option, even though the whole list is on screen.

Handle the arrow keys on the combobox, move the highlight one option per press with aria-activedescendant, and call preventDefault so the page doesn't scroll.

Severity: Critical

Reported as: Combobox not focused after action

Moving through the popup's 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 key that moves the highlight.

Severity: Serious

Reported as: Focus not updated with Home or End keys

In a select-only combobox, the Home key must move the highlight 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 highlighted option can also scroll out of view.

Handle Home and End on the combobox, move the highlight the same way the arrow keys do, and call preventDefault so the page doesn't scroll. In an editable combobox, Home and End can move the caret instead.

Severity: Moderate

Reported as: Arrow key navigation loop failed

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

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

When the last option is highlighted and the Down Arrow key is pressed, highlight the first option, and mirror that for the Up Arrow key, as the keyboard table under Operation describes.

Severity: Minor

Reported as: Arrow key navigation failed

The arrow keys that move through a combobox's popup should match its layout: the Down Arrow and Up Arrow keys for a vertical popup, and the Left Arrow and Right Arrow keys for a horizontal one.

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

Handle the pair of keys that matches the layout and the listbox's aria-orientation value.

Reported as: Skipping composite arrow key navigation

Every option in a combobox's popup should be reachable with the arrow keys in turn, not just the first few.

When the key handler covers only some options, such as the ones rendered before more results loaded, the highlight stalls 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.

Move the highlight through 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 combobox's popup must be reachable with the keyboard.

When the selected option is disabled while still shown as selected, or the key handler skips it, the arrow keys pass over the one option plainly marked as chosen. Keyboard users can't confirm or change their choice from it.

Highlight the selected option when the popup opens, and let the arrow keys reach it like any other option. When the selected option has to be disabled, clear the selection first.

Severity: Critical

Reported as: Possibly unsupported selection model

A combobox popup that accepts several options should let users select them without holding a modifier key, or implement the modifier-key model completely.

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

Make Space toggle the highlighted option without changing the others. In an editable combobox, where Space types a space, use another key and say which next to the combobox.

Reported as: Aria-expanded value did not change

When a key opens or closes a combobox's popup, the combobox's expanded state must change with it.

When the click handler updates aria-expanded and the key handlers don't, pressing the Down Arrow key opens a list that screen reader users are told is still collapsed. They get no confirmation that their key press did anything.

Route the keyboard and the pointer through one function that opens and closes the popup and sets aria-expanded in the same step. A <select> or an <input> with a <datalist> reports the change itself.

Severity: Serious

Reported as: Missing aria-expanded attribute

A custom combobox must carry aria-expanded, so a key press that opens its popup is reported.

When the attribute is missing, the popup opens from the keyboard with no state to report, so screen reader users don't learn a list appeared.

Give a custom combobox aria-expanded="false" in its first render, and set it to true while the popup is showing. Leave the state to the browser on a <select> or an <input> with a <datalist>.

Severity: Serious

Reported as: Spacebar does not trigger selection

In a select-only combobox, pressing Space while the popup is open must select the highlighted option, or toggle it in a popup that accepts several.

When the combobox 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 combobox, run the same code a click on the option 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 combobox popup that accepts more than one selected option must set aria-multiselectable="true" on its listbox.

The attribute defaults to false, so when it's missing, screen reader users aren't told they can choose more than one option. 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. Keep aria-selected on each option, true on the chosen ones and false on the rest.

Severity: Moderate

Reported as: Aria-expanded value did not change

A combobox's expanded state must change each time users open or close its popup.

When the state doesn't change as the popup opens, screen reader users hear the combobox as collapsed after they type or press the Down Arrow key. They can't tell whether operating it did anything.

Set aria-expanded in the same code that shows and hides the popup. Leave the state to the browser on a <select> or an <input> with a <datalist>, and add no aria-expanded to either.

Severity: Serious

Reported as: Missing aria-expanded attribute

A combobox must report whether its popup is open.

When a custom combobox has no expanded state, assistive technology has nothing to report as users operate it, so screen reader users can't tell whether the popup opened or closed.

Give a custom combobox aria-expanded="false" in its first render, and set it to true while the popup is showing.

Severity: Serious

Reported as: Disabled combobox active

A combobox that presents as disabled must not open its popup or change its value from the keyboard.

When the combobox is grayed out while its key handlers stay attached, keyboard users can open the list and set a value the form treats as unavailable. Screen reader users are told the combobox is disabled and then find that it works, with no way to tell which to believe.

Use the disabled attribute on an <input> or <select>, which stops interaction. When the combobox carries aria-disabled="true", return early from its key and click handlers.

Severity: Moderate

Reported as: Deprecated keypress listener

A combobox'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 combobox 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

Many relate to 1.3.1 Info and Relationships: having options, giving the popup's options the option role, naming the combobox and its popup, reporting and updating the expanded state, marking the chosen option, referencing the popup with aria-controls, keeping aria-activedescendant valid, keeping options out of the tab order, matching aria-haspopup to the popup's type, declaring autocomplete only where users can type, consistent set sizes and positions, and declaring a popup that accepts several options.

The roles, the options' names, the options' selection state, filtering the list as users type, redundant ARIA, how the disabled state is declared, and keeping controls out of the options relate to 4.1.2 Name, Role, Value.

Reaching the combobox, accepting an option with Enter, the active option when the popup opens, an available option, moving through the options with the arrow keys, Home, and End, matching aria-orientation to those keys, reaching the selected option, and selecting with Space relate to 2.1.1 Keyboard.

Keeping focus while users type and keeping the context when the value changes relate to 3.2.2 On Input, and keeping focus on the combobox while users move through the options relates to 1.3.2 Meaningful Sequence. Keeping the popup out of the tab order relates to 2.4.3 Focus Order.

Distinct option names, a valid aria-haspopup or aria-autocomplete value, declaring autocomplete, one selection attribute, a single aria-controls target, set sizes and positions on the options, a valid aria-orientation value, and wrapping 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 combobox with no role, no name, or no options, unnamed options, an expanded state that contradicts the screen, options with no selection state, an aria-activedescendant that names the wrong option, a combobox keyboard users can't reach or set with Enter, a popup with no available option, arrow keys that don't move through the options, or a selected option the keyboard can't reach.

Serious issues confuse users though tasks are still possible, such as duplicate option names, a list that doesn't filter, a missing or stale expanded state, a wrong disabled state, focus lost while typing, a value change that loads a page or submits the form, popup content without the option role, controls inside options, focus that leaves the combobox, an aria-orientation that contradicts the keys, or a select-only combobox that ignores Space.

An unnamed popup, a popup or options in the tab order, a disabled combobox that still responds, Home and End that don't move a select-only combobox's highlight, set sizes or positions that can't be true, and a missing aria-multiselectable, are Moderate. Minor issues include an invalid aria-haspopup, aria-autocomplete, or aria-orientation value, set sizes and positions on the wrong element, a highlight that doesn't wrap, gaps in aria-controls, mixing selection attributes, and an option holding the value that isn't marked selected.

The aria-owns checks, the check on where the role sits, and the checks on the arrow keys' layout, on reaching every option, and on the multi-select model carry no severity: Evinced reports them as general and sanity checks.