aria-autocomplete

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.
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.

© 2018 Digital Accessibility Implementations Resources. All rights reserved.

ARIA