Autocomplete

Autocomplete is an input field that enables selections or filters a list of options as the user types to present options.

Overview

Autocomplete is an input field that offers enhanced behaviors:

  1. The input filters the list when the values are restricted to the ones in the listbox.
  2. The popover displays possible suggestions but the user can also type values that aren’t shown in the listbox.

Anatomy

  1. Label: Describes the selection the user needs to make.
  2. Hint text (optional): Adds context to the label.
  3. Select field: Area that displays the selection made.
  4. Popover: Container that holds the list of options (listbox) when the autocomplete is active.
  5. Listbox: The list of options.
  6. List item: An individual option in the listbox.

Demo

Open the component in Figma.

When to use

Use autocomplete for these scenarios:

  • To filter or narrow down a long list of options, or one that is expected to grow over time.
  • To find a specific value within a list.
  • To suggest similar or previous searches.

When not to use

Use another type of input for scenarios when you have fewer options or more constraints.

Use a select instead:

  • If the list of options is not long.

Use a native select instead:

  • If your experience is mostly used on mobile or you need a native picker experience.
  • If there are performance constraints.

Use radio button group instead:

  • If there are only two or three options to choose from to reduce users’ cognitive load.

Similar components

Variants

Single select

Allows the user to select a single list item.

Multiselect

Allows the user to select multiple list items.

Properties

Grouping

List items can be grouped under a section heading, a dividing line, or a combination of both elements.

Behaviors

Placement

Placement is done automatically. The menu is positioned under its anchor element. If there isn’t room in the viewport, it will position on top of the anchor element.

Scrolling

When a menu has scrolling, the last item should be 50% visible in the container so that it’s clear that there is more content available.

Selection

  • When an list item is selected in a single select, the popover closes and the select field updates. The selected item no longer appears in the listbox.
  • When list items are selected In a multiselect, the popover remains open until the user closes the select field. The selected items are removed from the listbox.
  • In both cases, a user can close the listbox by clicking outside of the popover, using the esc key, or by focusing on a different area of the page.

Loading

The popover can show a loading state while data is being populated.

Empty state

The popover will display an empty state if there are no matching results.

 

Accessibility

Odyssey components are designed and built to meet accessibility requirements out of the box. So, designers and engineers can focus on any accessibility concerns unique to their problem areas.

Our components meet WCAG 2.2 AA criteria and WAI-ARIA guidelines to provide a usable and accessible experience to everyone. The autocomplete component is based on the ARIA 1.2 combobox pattern and the ARIA 1.2 Listbox pattern.

 

Content guidelines

Label

Describes the selection the user needs to make.

  • Every autocomplete requires a label.
  • Make it clear what types of options will be available.
  • Use three words or less.
  • Use sentence case.
  • Don’t use punctuation.
  • Avoid articles (the, an, a).
  • Be descriptive, not instructional.

Hint text (optional)

Adds context to the label, helps users understand the selection they need to make, or how they need to format or input a selection.

  • Optional.
  • Be concise. Try to use one short sentence. For example, Select a role for this admin.
  • Don’t restate the same information in the label to prompt users to interact with it.
  • Don’t add hint text only to maintain layout continuity with other inputs that require hint text.

Section heading (optional)

A subheading that groups related list items.

  • Options may be grouped for faster lookup.
  • One to three words.
  • Concisely label what the list items have in common.
  • Create at least two groups.
  • Make the group labels as parallel as possible for readability.

List item

The options users can select.

  • Be concise.
  • Make list item names harmonious and use words the user understands.
    For example: device one-time password, desktop one-time password, device security key not device OTP, one-time password for this computer, Yubikey for device.
  • Write in sentence case.
  • Don’t use end punctuation.
  • Order items in a logical, intentional way to help the user find a specific option. For example,
    - Most used to least used
    - Increasing order (smallest to largest)
    - Alphabetically
    - Recommended item first
  • If placeholder text is used instead of hint text use Select a {{country, role, date, etc.}}

Error message

Customize error messaging for autocomplete to explain what went wrong and how to fix it. As a default for the input:

Restricted number of menu items: Select an item.

Arbitrary number of menu items: Select or add an item.

Content accessibility

No additional content is needed for accessibility tags or labels.

 

Figma: Autocomplete