Autocomplete

General information

An autocomplete is a form field that allows the user to type in a text field while a menu displays below the field with a list of valid options. Autocomplete allows the user to view and (optionally) filter the list, then choose an item (or optionally, type in their own value). Autocomplete only allows the user to select one item.

In the language of the ARIA Authoring Practices Guide, the component we call the Autocomplete is a variant of what they call an editable Combobox. The menu used with the Combobox in an Autocomplete is a Listbox that contains List Items. We’re using that same language for better understanding.

There are four use cases for autocomplete:

1. Static suggestions: The user wants to type content into a field, and the implementing team wants to ensure that a specific list of potential values are provided. The list of values doesn’t change regardless of what the user typed in. For example, if the website was selling fruit and every time the user visits, they buy bananas, the system may suggest banana in the list items even if the user is typing in mango.
2. Open autocomplete: In an open autocomplete, the list of items is a suggestion and open to having the user enter something else. If the field label was favorite fruit the user could enter banana and the system would accept it, even if banana wasn’t in the list of fruit in the menu. Optionally, the system can automatically select the first option.
3. Closed autocomplete: In a closed autocomplete, the list of options is closed, and the user must choose something in the list. For example, if the website was selling fruit and the user typed in banana, but banana was not on the list because the store didn’t have any in stock, the field would automatically clear when the user moved of of it. Optionally, the system can automatically select the first option.
4. Inline autocomplete: In an inline autocomplete, as the user types the first item that displays is automatically selected. The portion of the selected suggestion that has not been typed by the user, appears inline after the input cursor in the text field. The inline completion string is visually highlighted and has a selected state. The designer can choose whether the inline autocomplete behaves as open or closed.

Related components

• Checkbox
• Radio buttons
• Select menu

When to use

Static suggestions

• When the business has decided to provide a list of suggestions for a specific field, and also that the user may enter something not in the list of suggestions.
• The list of suggestions is static and doesn’t change regardless of what the user types.

Open autocomplete

• When the implementing team has a list of items the user can choose from, and the user may choose one or enter something not on the list of items.
• The list of items is dynamic and changes depending on what the user types into the field. The more characters the user types, the more tightly filtered the results become.
• The user knows the name or a substring in the item they wish to choose. For example, if the user knows the product they wish to purchase has “Star Wars” in the name, they can filter by that phrase.
• The user wants to choose an item, but the list is so long as to be overwhelming.
• Be sure to inquire what the expected potential list of items is. If the list is short today but will be 2,000 items in two years, save time and use an autocomplete today.

Closed autocomplete

• When the implementing team has a list of items the user can choose from, and those are the only items the user may choose from.
• The list of items is dynamic and changes depending on what the user types into the field. The more characters the user types, the more tightly filtered the results become.
• The list of items is more than 10 items.
• The user knows the name or a substring in the item they wish to choose. For example, if the user knows the product they wish to purchase has “Star Wars” in the name, they can filter by that phrase.

Inline autocomplete

• The list of items is dynamic and changes depending on what the user types into the field. The more characters the user types, the more tightly filtered the results become.
• The list of items to be filtered is more than 10 items.
• The user’s string matches exactly to the string being entered, or we have extremely high confidence that it will. For example, mailing addresses.

When not to use

• Don’t use the static suggestion version if the autocomplete is closed. Use a select.
• Don’t use an autocomplete if the list is never more than 25 items and the user can’t add a different value. Use a select.
• Don’t use an autocomplete if the list is never longer than three items and the user can’t add a different value. Use a radio button set.
• Don’t use an autocomplete if the list is never longer than 25 items and the user can’t add a different value. Use a select.
• Don’t use an autocomplete if the user needs to browse the list to find their item. Menus are not a good place to browse. For example, if they know it was “a book about a space battle, and the ISBN number started with 09 — I’ll know it when I see it”, use a different data display such as a page of items or a table.
• Don’t use an autocomplete if the user can select more than one item. Display the options on the page or in a dialog and use checkboxes.
• Don’t use an autocomplete if the user cannot type in the field to filter or select an item. Use a dropdown (or, if in a form, a Select) instead.

How to use

Do:

• Choose the right autocomplete type by taking into account the size of the list, the speed with which you can pull back results, and the pattern that best matches your scenario.
• Pay close attention to the uniqueness of the strings in the data set. If you have significantly long and not-unique strings such that all 10 results will display the same value, you should consider using a different pattern. For example, if the maximum displayed string length is 15 characters for a user’s payment type, and all of the user’s credit cards begin with “Bank of America”, they won’t be able to differentiate between the cards.
• Do your best to avoid situations where the “loading” message will display. This may mean not validating the search string until 3 or 4 characters have been entered.
• Be careful and knowledgable about your data sets! A person can have a 2 character name, for example, so displaying an autocomplete menu of names after 3 characters would prevent that data item from ever displaying.
• Provide the options in the menu in an understandable sequence.
  • Understandable sequences include alphabetical listings, numerical value, lists like the days of the week or months of the year that are always in a specific order, etc.
  • The sequence should be apparent by looking at the list.
  • The user should not have the ability to reorder the way the data is sorted. Use a table for complex data manipulations.

Do not:

• Do not add additional tasks to the task of selecting a list item. The interaction with a long list of items is cognitively complex as it is. (See below for the pattern for “add a new [thing]”.)
• Do not override the key commands for the autocomplete.
• Do not make the menu choices so complex that they are difficult to read and navigate in a menu. For example, if you need to display name, address, contact information and balance for a user to identify the right customer, use a table in a drawer, a dialog or an expansion panel instead.

Anatomy

Components contained within it

An autocomplete generally consists of a text input and a listbox. If being used for searching, it may also include a search button. The list box contains list items.

Options

Types

Sizes

States

Variants

Modifiers

Content standards

Animation standards

Interactions

On first click, tap or focus

• When the autocomplete receives focus, DOM focus is placed on the combobox.
• When the menu is open, DOM focus remains on the combobox and it has aria-activedescendant set to a value that refers to the focused element within the menu.
  • This is the implementation recommended by the W3C, however, I’ve heard it can be a bear. Research the best way to implement and update these requirements.
• onfocus, the autocomplete positions the cursor in the field allows the user to begin typing in the field.
  • For static suggestions, the menu opens immediately.
  • For dynamically filtering suggestions:
    • if the text field was empty when the user focused on it, the menu stays closed until the user has typed the minimum number of characters necessary to open the menu.
    • If the text field was populated with an item in the list when the user focused on it, the menu opens and focus shifts to that item in the list. For example, if the user typed in banana, only entries that include the word banana would display and if banana is an entry in the list, it would be selected.
      • Autocomplete must be able to be set to an existing value on page load so that the implementing team have the option to ensure that information can be auto-populated.
        • If that value is no longer in the selection data, the implementing team may choose to do any of the following supported actions:
          • immediately put the field in error with an explanation in the error message
          • immediately put the field in warning with an explanation in the error message
          • accept the value anyway (i.e. re-add it)
      • Autocomplete must be able to be set to an existing value on page load so that the implementing team have the option to ensure that information can be auto-populated.
        • If that value is no longer in the selection data, the implementing team may choose to do any of the following supported actions:
          • immediately put the field in error with an explanation in the error message
          • immediately put the field in warning with an explanation in the error message
          • accept the value anyway (i.e. re-add it)
      • Autocomplete must be able to be set to an existing value on page load so that the implementing team have the option to ensure that information can be auto-populated.
        • If that value is no longer in the selection data, the implementing team may choose to do any of the following supported actions:
          • immediately put the field in error with an explanation in the error message
          • immediately put the field in warning with an explanation in the error message
          • accept the value anyway (i.e. re-add it)
    • The system must provide the option to display a message to the user indicating how many more items are available if the number of items available is greater than the number of items currently displaying.
      • For example: “9 of 11 items displaying. Continue typing to filter the list.”
      • The implementing team may set the minimum number of characters necessary to open the menu to 0. This isn’t recommended for most situations.

On text entry

• When the user enters the set number of keystrokes, the menu opens.
• The system will display up to 10 values from the data set based on the string entered.
  • 10 values is dependent on how easily the user can see all 10 values. Ideally you don’t want the menu to scroll.
  • If the data set is empty and this is an open autocomplete, you may choose to show a list item that explains there are no matches.
  • If the data set is empty and this is a closed autocomplete, the system must display a message indicating that there are no results and tell them what to do about that.
  • The implementing team must be able to choose whether the user’s string matches only the beginning of the list items or matches anywhere in the list item.
    • For example, if the list is filtering US States and the user types in d they want Delaware, not North Dakota, so the designer should choose to filter from the front, and Delaware would be the only valid result.
    • If the list is filtering breeds of rabbit, on the other hand, the designer should choose to filter from anywhere in the string so that filtering by giant will bring up the British Giant, Checkered Giant, etc.
• As the user types, the system will filter the items in the data set, potentially all the way to an empty list.
  • If the data set is empty after filtering, the system must show a “No results” message with instruction to modify their search string.
• If the dataset’s first 10 items cannot be displayed in 400m, the system must display a loading message.
  • As the contents are changing, the user on a screen reader must be notified when the loading is complete and the new list items have loaded.

On keyboard entry

• When the menu is open, down arrow moves focus and selection to the next option. When it reaches the bottom of the list, it should loop back to the top and focus on the combobox. Another down arrow should return focus to the first item in the listbox.
• When the menu is open, up arrow moves focus and selection to the previous option. When it reaches the top of the list, it should focus on the combobox. Another up arrow should return focus to the last item in the listbox.
• When the menu is open, right arrow returns focus to the combobox without closing the menu, and moves the cursor one character to the right.
• When the menu is open, left arrow returns focus to the combobox without closing the menu, and moves the cursor one character to the left.
• When the menu is open, Home moves focus and selection to the first option.
• When the menu is open, End moves focus and selection to the last option.
• When the menu is open, typing any printable character moves focus back to the combobox and adds the character in the position of the cursor and selection to the next item with a name that starts with that named character.

On click, tap, or Enter of a menu item

• The system selects the list item, the listbox closes, and the cursor returns to the end of the text string in the combobox.

On leaving the Autocomplete

How an autocomplete behaves when the user leaves the field depends on whether the autocomplete is open or closed.

Open Autocomplete

• If the user selected a value OR there is an exact matching value in the list, the combobox will contain the selected value onblur.
• If the user did not select a value AND there is no matching value in the list, the combobox will contain the user’s typed value onblur .

Closed Autocomplete

• If the user selected a value, OR there is no exact match of a value from the menu, the combobox will contain the selected value onblur.
• If the user did not select a value, AND there is no exact match of a value from the menu, the system will clear the combobox value onblur.

Presentation

Placement

Hierarchy

Alignment

Composability

Responsive behavior

Spacing

Accessibility guidelines

Guideline 1.1.1 Non-Text Content

• If there is an icon in the form field, the icon is decorative and must be hidden from assistive technology.
• If there is an icon in the loading message, the icon is decorative and must be hidden from assistive technology.

Guideline 1.3.1 Info and Relationships

• The form field must have a programmatically associated text label.
• If the listbox contains one or more option groups, each option group must contain at least one option.
• If the listbox contains one or more option groups, each option group must have a programmatically-assigned accessible name via the aria-label or aria-labelledby attributes.
• A selected item must be specified with aria-selected=true. Selectable but unselected items must be specified with aria-selected=false. No more than one item may be selected at a given time.
• If the complete set of available items is not present in the DOM due to dynamic loading as the user scrolls, their aria-setsize and aria-posinset attributes must be set appropriately.
• The text box that serves as an input and displays the form field value has aria-role=combobox.
• The combobox element has aria-controls set to a value that refers to the menu.
• The menu has a role listbox.
• The menu is marked as aria-expanded=false when closed and aria-expanded=true when open.
• The autocomplete has an aria-autocomplete value that corresponds to its behavior:
  • none is when the menu has the same entries regardless of what the user types. (This is necessary for an autocomplete with static suggestions.)
  • list is when the values in the menu correspond to the values the user is typing. (This is necessary for the open and closed autocompletes.)

Guideline 1.3.5 Identify Input Purpose

If the field is being used for one of the Input Purposes for User Interface Components, ensure that the field is programmatically identified as such so that assistive technology such as autofill will function correctly. (This applies only to open autocomplete fields.)

Guideline 1.4.1 Use of Color

Do not use color alone to differentiate between enabled, disabled, and read-only items in the menu.

Guideline 1.4.3 Contrast (Minimum)

Text in the label, text field, and list items must meet a minimum contrast of 4.5:1 to its background. Disabled items are excepted from this guideline but read-only items, and items in hover or active states, are not excepted.

Guideline 1.4.4 Resize Text

The text in the autocomplete and its menu can be zoomed up to 200% without loss of content or functionality. See Scaling form elements which contain text by the W3C for technique information.

Guideline 1.4.10 Reflow

The autocomplete can be presented on a screen that is 320 CSS pixels by 256 CSS pixels without scrolling in two dimensions.

Guideline 1.4.11 Non-Text Contrast

The autocomplete’s borders have at least a 3:1 contrast to their background.

Guideline 1.4.12 Text Spacing

The autocomplete still works without loss of content and functionality when the following style properties are applied:

• Line height (line spacing) to at least 1.5 times the font size;
• Spacing following paragraphs to at least 2 times the font size;
• Letter spacing (tracking) to at least 0.12 times the font size;
• Word spacing to at least 0.16 times the font size.

DS Team: You may want to try this (experimental) text-spacing bookmarklet by Steve Faulkner for testing.

Guideline 2.1.1 Keyboard

See the list of keyboard interactions above.

Managing focus in the field at the top while also allowing the menu to be open and navigable may require using the aria-activedescendant property. Read the “Managing Focus in Composites Using aria-activedescendant” section in Developing a Keyboard Interface for more information.

Guideline 2.1.2 No Keyboard Trap

Failing this criteria has the potential to force the user to shut their entire browser down, making it a top priority to fix. See Conformance Requirement 5.

Ensure that when using keyboard navigation into and out of the listbox, the user is able to enter the combobox and listbox with the keyboard using either arrow or tab keys, as well as leave the listbox and combobox.

Guideline 2.3.3 Animation from Interaction

This is a AAA guideline, however in certain circumstances it has the ability to physically harm the user, making it a top priority.

If there are animations applied to the opening and closing of the menu, the animations can be disabled. There are two ways to accomplish this:

1. Check for and respect the CSS reduce motion query by not applying animation when the value is set to reduce.
2. If Platform has implemented a platform-wide user setting for end users to set, do not apply animation when the user has requested reduced motion.

Guideline 2.4.6 Headings and Labels

The form field must have a programmatically associated text label. (Yes this is the 2nd guideline covering this. They’re serious about it.)

Guideline 2.4.7 Focus Visible

When navigating by keyboard, any component that has focus must have a visible focus indicator. This includes both the text field and the menu. For more details, see Guideline 2.4.13 Focus Appearance.

Guideline 2.4.11 Focus Not Obscured

The menu can’t obscure the text field when the autocomplete is in focus.

Guideline 2.4.13 Focus Appearance

The following requirements are for a WCAG AAA guideline, and therefore are not “musts” but rather “shoulds” – designers who follow these guidelines significantly increase the usability of keyboards on the site.

When the autocomplete has focus, an area of the focus indicator meets all the following:

• is at least as large as the area of a 2 CSS pixel thick perimeter of the unfocused component or sub-component, and
• has a contrast ratio of at least 3:1 between the same pixels in the focused and unfocused states.

Guideline 2.5.1 Pointer Gestures

A user can use a single pointer to manipulate the component. Any multi-point or path-based gesture actions can also be completed with a single pointer.

Guideline 2.5.2 Pointer Cancellation

For functionality that can be operated using a single pointer, at least one of the following is true:

• No Down-Event: The down-event of the pointer is not used to execute any part of the function;
• Abort or Undo: Completion of the function is on the up-event, and a mechanism is available to abort the function before completion or to undo the function after completion;
• Up Reversal: The up-event reverses any outcome of the preceding down-event;
• Essential: Completing the function on the down-event is essential.

Guideline 2.5.3 Label in Name

The visible label must be included in the accessible name. For example, on a page with both a shipping address and a billing address, the visual label of each group’s City field may be “City” and the accessible names may be set to “Shipping – City” and “Billing – City”. Note that both contain the word “city” in the visible label.

Guideline 2.5.6 Concurrent input mechanisms

The component doesn’t force the user to use touch, mouse, or keyboard (etc.) unless certain exceptions are in play. Note: this means a user can switch from a mouse to a keyboard and back in the same interaction.

Guideline 2.5.7 Dragging Movements

If the menu item can be chosen by down-clicking the combobox then dragging down the listbox and releasing the click on the item to be selected, that isn’t the only way that menu items can be chosen.

Guideline 2.5.8 Target Size (Minimum)

The targetable areas of the autocomplete (the text field, the menu items) are at least 24px by 24px except where:

• Spacing: undersized targets are positioned so that if a 24 CSS pixel diameter circle is centered on the bounding box for each, the circles don’t intersect another target or the circle for another undersized target.
• Equivalent: the function can be achieved through a different control in the autocomplete
• Inline: the target is in a sentence or its size is otherwise constrained by the line height of non-target text
• User agent control: the browser default determined the size of the target and we didn’t modify it
• Essential: the presentation of the target is essential or legally required.

Guideline 3.1.2 Language of Parts

• This guideline is not needed today (24 March 2024). It is included because the work to localize our entire component set will be significant, so any pre-planning we can do is for the better.

• If and when we reach a point of localizing / internationalizing our content, we must ensure that we align with Guideline 3.1.1 Language of Page by declaring a default language for all of the content.
• 3.1.2 states that any parts of the page that do not use the default language are wrapped in a language tag indicating what language they are using. The most likely part of the autocomplete to need such wrapping would be a list item from the menu.

Guideline 3.2.1 On Focus

When the combobox or one of its list items gains focus, the system cannot automatically change context. For example, focusing on a list item cannot immediately open a dialog containing a different context or move the user to a different page.

Guideline 3.2.2 On Input

When the autocomplete changes values or settings, the system cannot automatically change context. For example, typing the letter d into the field cannot immediately open a dialog containing a different context or move the user to a different page.

Designers: the user selecting a list item named “Add a [thing]” is not considered “automatically changing context” but it can still be quite a surprise to the user, so if you choose to do this, provide ample warning in the list item.

Guideline 3.3.1 Error Identification

If the system can identify an error the user made while completing the autocomplete, the error should be identified and described in text.

The autocomplete must be designed to work with the form elements that display error messaging and warning messaging.

The error state must not display until the user moves focus off the component.

Guideline 3.3.2 Labels or Instructions

Labels or instructions are provided when content requires user input.

The autocomplete must be designed to work with the form elements that display instructions. The instructions must be coded in such a way that they are read to the user as part of the label for assistive technology.

If the label does not make it clear to the user what’s going to happen when they activate the autocomplete, the system must provide instructions. For example, closed autocomplete fields should tell the user they must choose from the list.

Designers: placeholder text is not accessible and should not be used for instructions.

Guideline 3.3.7 Redundant Entry

• Information previously entered by or provided to the user that is required to be entered again in the same process is either auto-populated or available for the user to select.
  • For example, if the user creates a vendor, then needs to edit the vendor, all of the information previously provided when creating the vendor should be pre-populated in the form for editing the vendor.

Guideline 4.1.2 Name, Role, Value

The autocomplete’s name and role can be programmatically determined, states, properties, and values set by the user can be programmatically set, and notification of changes is available to user agents including assistive technologies.

This also means that the subcomponents – such as listbox – also must meet this success criterion.

DS Developers: This is primarily for custom interface components like autocomplete. Standard HTML controls already meet this criterion. Use HTML elements whenever possible.

Guideline 4.1.3 Status Messages

Error or warning messages can be programmatically determined through role or properties so that they can be presented to the user by assistive technologies without receiving focus.

This means that however we choose to handle form element error messages, it works for autocomplete as well.

Guidelines for using

Anyone who uses this component should make sure to be aware of these responsibilities.

Guideline 1.1.1 Non-Text Content

• If there is an icon in the list items for the autocomplete:
  • If the icon provides meaning to the user, the icon is content and alternative text must be provided for assistive technology.
  • If the icon does not provide meaning to the user, the icon is decorative and must be hidden from assistive technology.

Guideline 3.2.4 Consistent Identification

• If there are two identical autocomplete fields on the page, they should be labeled consistently.

Guideline 3.3.1 Error Identification

If the system can identify an error the user made while completing the autocomplete, the error should be identified and described in text.

The design system provides error messaging capabilities as part of forms. As a user of the design system, you are responsible for identifying error scenarios, crafting error messaging, and implementing the messaging using the options provided by the design system. For example, a closed autocomplete that is a required field may clear automatically if the user types in their own value and then moves to the next field. The autocomplete must move to an error state and inform the user of the blank required field.

Guideline 3.3.2 Labels or Instructions

Labels or instructions are provided when content requires user input.

The design system provides instruction messaging capabilities as part of forms. As a user of the design system, you are responsible for identifying scenarios where the user needs clear instructions, crafting those instructions, and implementing the instructions using the options provided by the design system. For example, closed autocomplete fields must tell the user they must choose from the list.

Guideline 3.3.3 Error Suggestion

• If the system automatically detects an error and can determine what the user did wrong, the system should suggest a solution to the user.
  • “An error has occurred” is not a conformant error message when the problem is that the field is required.
  • “Select a choice from [fieldname]” indicates that we’ve identified what went wrong (field is blank) and what the user needs to do to fix it.

Additional resources

• Accessible Autocomplete Examples by alphagov and the accompanying GitHub page for accessible autocomplete.
• Best practices for the accessibility of an autocompletion component by Orange
• Building an Accessible Autocomplete Control by Adam Silver
• WCAG Quickref Guidelines
• Combobox Pattern
• Listbox Pattern