ACTION-2039: Update definition of aria-autocomplete

Update definition of aria-autocomplete

Matthew King
Due on:
March 17, 2016
Created on:
March 10, 2016
Associated Product:
ARIA 1.1
Related emails:
No related emails

Related notes:

The objectives of this action and its proposal[1] are to clarify the meaning of the different values of aria-autocomplete and clearly state the authoring requirements for using them.
It does not change the values or meanings; it is an attempt to describe the ARIA 1.0 intent derived from discussion on the public ARIA mailing list.[2] [3]
It also harmonizes the language with the ARIA 1.1 definition of the combobox role and haspopup property.

This proposal is particularly important to the goals of improving both authoring of and support for elements with autocomplete behavior, especially comboboxes.
It will also facilitate appropriate use of autocomplete in design patterns other than combobox.

The proposal for revisions to the aria-autocomplete section of the specification is in branch action2039-autocomplete.[1] It includes the following changes.

1. The first paragraph revises the short definition of the property to emphasize that:
A. The property both indicates whether an elemet provides autocomplete behavior and what type of behavior is provided.
B. Autocomplete behavior is limited to suggesting values that would complete input based on some amount of input that has been provided by the user; autocomplete behavior does not exist where only some arbetrary values unrelated to the user's input are suggested.

2. Added a paragraph that summarizes how each of the autocomplete values describe a specific type of interaction model.

3. Added a paragraph that describes the difference between an input that provides an autocomplete list and an input that provides a popup list of suggested values but does not have autocomplete behavior.

4. Clarified the intent of the normative authoring statement regarding the selection state for inline suggestions.

5. Added a normative authoring requirement to provide an appropriate value for aria-haspopup when autocomplete is list or both.

6. Added a description of the difference between implementations that pre-select a specific value from a list and implementations that require the user to take specific actions to select a suggestion.

7. Added a normative authoring requirement to use aria-activedescendant when autocomplete is list or both and when the autocomplete implementation automatically pre-selects a specific suggestion.

8. Added a paragraph to clarify that autocomplete is a property, not a state, and what that means in practice, e.g., authors should not dynamically change its value to reflect the presence of autocomplete suggestions.

9. Added a normative authoring requirement that states that authors should use aria-expanded to communicate the presence of the suggestion container element when autocomplete is list or both.

10. Adjusted the language throughout the entire description to emphasize that the "list" value refers to a collection of suggestions that is presented in a separate element and that element is not necessarily a listbox. This is to make it compatible with the ARIA 1.1 combobox support for elements other than listbox.

11. reworded the descriptions in the value table for autocomplete to make it clear the values describe what an element will do (they are a property) rather than what an element is doing (they are not reflecting a state).

[1] action2039-autocomplete branch:

[2] List post describing the difference between values list and none:

[3] List post describing inline and list with Microsoft references:

Matthew King, 21 May 2016, 05:47:30

Made the following revisions to the proposed aria-autocomplete description to address feedback provided in the June 2, 2016 ARIA caucus.

1. For inline autocomplete, revised language to removed the word "state" when refering to selected text to address concerns that authors may think that aria-selected needs to be applied to text input.

2. Added an author MUST statement requiring aria-controls to be used if aria-autocomplete is set to list or both.

3. Changed the tense used in the values table from future to present.

4. Fixed some typos.

Also made additional improvements to address issues I discovered while completing the above revisions.

if the user provides input for which the application is unable to make a prediction of the user's intent, there will not be any suggestions for how to complete the input.
The property definition and value definitions did not effectively communicate this conditional nature of the appearance of predictions.


1. In the first paragraph that provides the property definition, changed "triggers" to "could trigger" and added an if statement to the second half of the definition.

2. In the value definitions table, incorporated the word "may" to reflect the conditional nature of autocomplete behavior.

Issue: The paragraph describing limitations on the appropriate use of aria-autocomplete to predictive behaviors implied authoring requirements without a normative authoring statement.

Resolution: Added an author SHOULD statement describing when to set aria-autocomplete to none even if input proposals are provided.

Issue: the prose for normative conditions was dense, making it difficult to parse out all applicable normative requirements for some situations.

Resolution: Simplified the presentation of normative requirements by using ordered lists where multiple requirements apply to the same set of conditions.

Matthew King, 9 Jun 2016, 08:18:23

Merged (via PR to preserve all Matt's commit history):

(Made whitespace consistent with rest of spec and fixed broken tag separately:

Given that the changes have been merged into master, setting State to CLOSED.

Joanmarie Diggs, 21 Jun 2016, 21:44:44

Display change log.

James Nurthen <>, Valerie Young <>, Chairs, Daniel Montalvo <>, Staff Contact
Tracker: documentation, (configuration for this group), originally developed by Dean Jackson, is developed and maintained by the Systems Team <>.
$Id: 2039.html,v 1.1 2023/05/22 16:31:52 carcone Exp $