aria-autocomplete attribute indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a
textbox and specifies how predictions will be presented if they are made.
Autocompletion is user interface feature wherein inline suggestions are 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 becomes the value if the user performs an action, such as tabbing, that causes focus to leave the field.
aria-autocomplete property describes the type of autocompletion interaction model a textbox, searchbox, or combobox will use when dynamically helping users complete text input. It distinguishes between two models: the inline model (
aria-autocomplete="inline"), which presents a single predicted value and the list model (
aria-autocomplete="list"), which presents a collection of possible values in a separate element that pops up next to or below the text input, similar to a
<datalist>. A third value,
aria-autocomplete="both" is for when the interface will present a list while also including a predicted value. The default is
none, meaning the textbox, searchbox, or combobox will not provide an auto complete value.
If the suggested autocomplete value provides suggested values that aren't dependent on the input provided by the user, consider omitting autocomplete for everyone. For example, a searchbox input displaying unfiltered recent search terms may be helpful to a marketing team on an eCommerce site, but likely isn't helpful for the screen reader user. When it is best to not specify a value for
aria-autocomplete or to set the value to the
none default, likely your non-assistive technology users also don't need the experience.
When implementing autocomplete functionality, ensure the suggested portion of the value is presented as selected text to enable distinguishing between a user's input and the suggestion. Make sure that when the suggested value is not the desired value, users can easily delete the suggestion or replace it by continuing to type.
When implementing a list of values, DOM focus should remain on the text input while the suggestion list is displayed.
aria-controlswith the value of the id of the suggested list of values.
aria-haspopupmatching the role of the element that contains the collection of suggested values.
- manage focus, if required, including using
aria-activedescendantif the collection container supports.
- use the
aria-expandedstate on the list to communicate that the list is displayed.
If an autocomplete list value is automatically accepted when the field loses focus, the list must be contained in a role that supports
aria-activedescendant, with the value of
aria-activedescendant on the input field dynamically adjusted to refer to the element containing the selected suggestion.
When a user is providing input, not automatic suggestion is displayed.
aria-autocomplete="inline"text suggesting one way to complete the provided input may be dynamically inserted after the caret.
aria-autocomplete="list"When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.
aria-autocomplete="both"an input to offer both models at the same time. 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.