aria-autocomplete

When to use

On a custom role="combobox" or role="textbox" that offers suggestions as the user types. The attribute tells AT what kind of autocomplete behaviour to expect, so the user can anticipate whether to look in the input itself, in a popup list, or both.

Do not put it on a plain native <input type="text"> that has no suggestion mechanism — there’s nothing to announce.

This attribute is often confused with the HTML autocomplete attribute. They are unrelated. HTML autocomplete ("email", "current-password", "street-address", …) tells the browser how to fill the field. aria-autocomplete tells assistive tech what UI pattern the developer has implemented. Both can appear on the same input and they don’t conflict.

How it behaves

Accepts four token values:

• "none" — the default. The textbox does not autocomplete. You usually don’t need to set this explicitly.
• "inline" — as the user types, suggested text is appended to the input itself, typically selected so the next keypress can overwrite it.
• "list" — suggestions appear in a separate popup (usually a role="listbox"). The input value does not change automatically.
• "both" — both at once: the popup list is visible and the top suggestion is inlined into the input.

Use the value that matches what your implementation actually does. If your combobox shows a dropdown of options but does not modify the input as the user types, that’s "list", not "both".

Common failures

• Confusing it with the HTML autocomplete attribute. They look similar, do different things, and you usually need both.
• Setting aria-autocomplete="list" but not also setting aria-controls to point at the listbox, and aria-expanded to track open/closed.
• Setting aria-autocomplete="both" when the input never autofills. The user hears the affordance and waits for an inline suggestion that never appears.
• Putting aria-autocomplete on a control that isn’t a textbox or combobox — for example, a button. The attribute is ignored.
• Forgetting to manage aria-activedescendant for the highlighted option in the list. The user hears that suggestions exist but cannot tell which one is currently active.
• Hard-coding aria-autocomplete="list" without checking screen-reader output. Many AT have inconsistent announcement patterns, and the wrong token produces confusing phrasing.

Example

<label for="city">City</label>
<input
  id="city"
  role="combobox"
  type="text"
  autocomplete="address-level2"
  aria-autocomplete="list"
  aria-controls="city-listbox"
  aria-expanded="true"
  aria-activedescendant="city-opt-3"
>
<ul id="city-listbox" role="listbox">
  <li id="city-opt-1" role="option">Bristol</li>
  <li id="city-opt-2" role="option">Birmingham</li>
  <li id="city-opt-3" role="option">Brighton</li>
</ul>