Accessible Combobox & Autocomplete Guide

The WCAG 2.2 Criteria a Combobox Must Satisfy

See the full picture in the WCAG 2.2 Level AA requirements and work through the interactive WCAG 2.2 checklist.

2. Anatomy: The Roles, States, and Properties

An ARIA combobox has four parts: the input, the popup, the options, and a separate live region that announces the result count. The most important detail — the one that broke in older tutorials — is that role="combobox" goes on the input itself, not on a wrapper.

The three aria-autocomplete values describe how typing relates to the list: "list" shows filtered suggestions in the popup (the common case), "both" also completes the input inline with the rest of the top match, and "none" means the list is not filtered by what you type. For how each attribute is exposed to assistive technology, see the ARIA roles & attributes reference.

4. The Conformant HTML Markup

Here is an editable combobox with list autocomplete in its open state, with the first option active. Note the role="combobox" on the input, the paired aria-controls / id, and the separate aria-live region that is not inside the listbox.

<label id="fruit-label" for="fruit">Choose a fruit</label>

<input
  id="fruit"
  role="combobox"
  aria-labelledby="fruit-label"
  aria-controls="fruit-listbox"
  aria-expanded="true"
  aria-autocomplete="list"
  aria-activedescendant="fruit-opt-0"
  autocomplete="off"
  type="text"
/>

<ul id="fruit-listbox" role="listbox" aria-label="Fruit">
  <li id="fruit-opt-0" role="option" aria-selected="true">Apricot</li>
  <li id="fruit-opt-1" role="option">Avocado</li>
  <li id="fruit-opt-2" role="option">Banana</li>
</ul>

<!-- Separate polite live region for the result count -->
<div class="sr-only" aria-live="polite">3 results available</div>

When the popup is closed, set aria-expanded="false", remove aria-activedescendant, and hide (or remove) the listbox. Setting autocomplete="off"on the input stops the browser's own autofill dropdown from colliding with yours.

6. Wiring It Up in Vanilla JavaScript

This handler shows the core mechanics: filter on input, open and close the popup, move the active option with aria-activedescendant, select on Enter, and announce the count. It is deliberately minimal so the moving parts are visible.

const input = document.getElementById("fruit")
const listbox = document.getElementById("fruit-listbox")
const status = document.querySelector("[aria-live]")
const ALL = ["Apricot", "Avocado", "Banana", "Cherry", "Date"]
let activeIndex = -1
let options = []

function open() {
  input.setAttribute("aria-expanded", "true")
  listbox.hidden = false
}
function close() {
  input.setAttribute("aria-expanded", "false")
  input.removeAttribute("aria-activedescendant")
  listbox.hidden = true
  activeIndex = -1
}

function render(matches) {
  listbox.innerHTML = ""
  options = matches.map((label, i) => {
    const li = document.createElement("li")
    li.id = "fruit-opt-" + i
    li.role = "option"
    li.textContent = label
    li.addEventListener("click", () => select(i))
    listbox.append(li)
    return li
  })
  status.textContent = matches.length
    ? matches.length + " results available"
    : "No results found"
}

function setActive(i) {
  options.forEach((o) => o.classList.remove("is-active"))
  activeIndex = (i + options.length) % options.length
  const el = options[activeIndex]
  el.classList.add("is-active")
  el.setAttribute("aria-selected", "true")
  input.setAttribute("aria-activedescendant", el.id) // virtual focus
  el.scrollIntoView({ block: "nearest" })
}

function select(i) {
  input.value = options[i].textContent
  close()
}

input.addEventListener("input", () => {
  const q = input.value.toLowerCase()
  render(ALL.filter((x) => x.toLowerCase().includes(q)))
  open()
})

input.addEventListener("keydown", (e) => {
  const isOpen = input.getAttribute("aria-expanded") === "true"
  if (e.key === "ArrowDown") { e.preventDefault(); isOpen ? setActive(activeIndex + 1) : open() }
  else if (e.key === "ArrowUp") { e.preventDefault(); setActive(activeIndex - 1) }
  else if (e.key === "Enter" && activeIndex > -1) { e.preventDefault(); select(activeIndex) }
  else if (e.key === "Escape") { close() }
})

Two details matter most: setActive() only ever changes aria-activedescendant and a class — it never calls focus() — and the result count is written into the polite live region on every filter, satisfying 4.1.3 Status Messages. Debounce that announcement for fast typists.

How to Test an Accessible Combobox

Automated scanners confirm the roles exist and aria-controls resolves, but only a manual pass proves the focus model and announcements actually work. Run this on every combobox:

1. Operate it with the keyboard only. Tab to the input, type to filter, arrow through options, Enter to select, Escape to dismiss — no mouse, no dead ends.
2. Watch the caret. As you arrow through options, the text cursor must stay in the input. If focus jumps into the list, the aria-activedescendant model is broken.
3. Listen with a screen reader. You should hear “combobox,” the expanded state, each active option as you arrow, and the result count when it changes. Verify with the screen reader testing guide.
4. Filter to zero results. A “No results found” message is announced, and there is no stale active option left behind.
5. Check the label. The combobox has a real, persistent accessible name — not just a placeholder.

Then layer automated checks on top with axe-core, and see automated vs manual testing for where each fits. Scan the live page with the URL accessibility auditor.

Accessible Combobox Checklist

1. Right pattern. There is a real, navigable popup of options — not just a search field. If <datalist> fits, use it.
2. Role on the input. role="combobox" is on the focusable input, not a wrapper, with aria-controls to the listbox.
3. State is live. aria-expanded flips true/false as the popup opens and closes.
4. Virtual focus. Arrow keys move aria-activedescendant; real focus never leaves the input.
5. Options are options. role="listbox" with role="option" children, each with a stable id and aria-selected on the chosen one.
6. Count announced. A polite aria-live region reports results (4.1.3).
7. Real label. A persistent accessible name via <label> or aria-labelledby.

Work through the full WCAG 2.2 checklist to see the combobox in the context of every other requirement.