WAI-ARIA: aria-autocomplete (Property)

Description

Indicates whether inputting text could trigger display of one or more predictions of the user’s intended value for an input and specifies how predictions would be presented if they are made.

The aria-autocomplete property describes the type of interaction model a textbox, searchbox, or combobox employs when dynamically helping users complete text input. It distinguishes between two models: the inline model (aria-autocomplete=”inline”) that presents a value completion prediction inside the text input and the list model (aria-autocomplete=”list”) that presents a collection of possible values in a separate element that pops up adjacent to the text input. It is possible for an input to offer both models at the same time (aria-autocomplete=”both”).

The aria-autocomplete property is limited to describing predictive behaviors of an input element. Authors SHOULD either omit specifying a value for aria-autocomplete or set aria-autocomplete to none if an input element provides one or more input proposals where none of the proposals are dependent on the specific input provided by the user. For instance, a combobox where the value of aria-autocomplete would be none is a search field that displays suggested values by listing the 5 most recently used search terms without any filtering of the list based on the user’s input. Elements with a role that supports aria-autocomplete have a default value for aria-autocomplete of none.

When an inline suggestion is made as a user types in an input, suggested text for completing the value of the field dynamically appears in the field after the input cursor, and the suggested value is accepted as the value of the input if the user performs an action that causes focus to leave the field. When an element has aria-autocomplete set to inline or both, authors SHOULD ensure that the automatically suggested portion of the text is presented as selected text. This enables assistive technologies to distinguish between a user’s input and the automatic suggestion and, in the event that the suggestion is not the desired value, enables the user to easily delete the suggestion or replace it by continuing to type.

If an element has aria-autocomplete set to list or both, authors MUST ensure both of the following conditions are met:

1. The element has a value specified for aria-controls that refers to the element that contains the collection of suggested values.
2. Either the element or a containing element with role combobox has a value for aria-haspopup that matches the role of the element that contains the collection of suggested values.

Some implementations of the list model require the user to perform an action, such as moving focus to the suggestion with the Down Arrow or clicking on the suggestion, in order to choose the suggestion. In such implementations, authors MAY manage focus by either using aria-activedescendant if the collection container supports it or by moving DOM focus to the suggestion. However, other implementations of the list model automatically highlight one suggestion as the selected value that will be accepted when the field loses focus, e.g., when the user presses the Tab key or clicks on a different field. If an element has aria-autocomplete set to list or both, and if a suggestion is automatically selected as the user provides input, authors MUST ensure all the following conditions are met:

1. The collection of suggestions is presented in an element with a role that supports aria-activedescendant.
2. The value of aria-activedescendant set on the input field is dynamically adjusted to refer to the element containing the selected suggestion as described in the definition of aria-activedescendant
3. DOM focus remains on the text input while the suggestions are displayed.

The aria-autocomplete property is not intended to indicate the presence of a completion suggestion, and authors SHOULD NOT dynamically change its value in order to communicate the presence of a suggestion. When an element has aria-autocomplete set to list or both, authors SHOULD use the aria-expanded state to communicate whether the element that presents the suggestion collection is displayed.

Browser Compatibility

Screen Reader Support

aria-autocomplete Example

HTML Example

A page contains a combobox composed of a textbox and a dropdown list of values which the user may choose from. The chosen list item becomes the value of the textbox. As the user navigates through the list via arrow keys, the aria-activedescendant property is adjusted to reflect the id attribute of the current child element which has been navigated to.

<input type="text" aria-activedescendant="cb1-opt6" aria-readonly="true" aria-owns="cb1-list" aria-autocomplete="list" role="combobox" id="cb1-edit">
<ul aria-expanded="true" role="listbox" id="cb1-list">
  <li role="option" id="cb1-opt1">Alabama</li>
  <li role="option" id="cb1-opt2">Alaska</li>
  <li role="option" id="cb1-opt3">American Samoa</li>
  <li role="option" id="cb1-opt4">Arizona</li>
  <li role="option" id="cb1-opt5">Arkansas</li>
  <li role="option" id="cb1-opt6">California</li>
  <li role="option" id="cb1-opt7">Colorado</li>
</ul>

Characteristics

Used in Roles

• combobox
• textbox

Inherits into Roles

• searchbox

Value

• token-
  One of a limited set of allowed values. An explicit value of undefined for this type is the equivalent of providing no value.
• inline
• When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret.
• list
  • When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.
• both
  • When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.
• none (default)
  • When a user is providing input, an automatic suggestion that attempts to predict how the user intends to complete the input is not displayed.

Semantic HTML

Use the HTML5 “autocomplete” attribute.

<form action=”/action_page.php” autocomplete=”on”>
First name:<input type=”text” name=”fname”><br>
Last name: <input type=”text” name=”lname”><br>
E-mail: <input type=”email” name=”email” autocomplete=”off”><br>
<input type=”submit”>
</form>

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-autocomplete.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for aria-autocomplete.
• MDN Web Docs
  The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-autocomplete.