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.

Single Select

Multiselect

Allows the user to select multiple list items.

Multiselect

Inline

For autocompletes that appear on the same horizontal line as another field.  This variant allows hidden labels.

Ref to 2352:38711

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.

States

Focus

The focus state displays the hover state with an additional highlight to visualize the interaction more easily when navigating with a keyboard.

Disabled

The disabled state prevents a user from initiating an action. The context of the page or component should make it clear why the element is disabled and what needs to change in order to be able to use it.

Read-only

A read-only input can’t be edited, but users can interact with the field to select and copy its content.

The value of a read-only field is submitted if it’s in a form.

Error

Use inline validation whenever possible.

  • If there is an error, an error message should be displayed as soon as the user has made a selection, without the user needing to submit the field.
  • If the field has an error displayed, remove the error state once their input is valid.
  • Inline errors may include multiple errors.

Error messages in Odyssey are displayed under input fields. Errors don’t replace hint text, which appears above the input area.

Inline ERROR single
Inline ERROR multiple

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.
  • If using an inline variant, the label can be hidden.
    • In Figma, you can either hide the label layer, or use the various Input field subcomponents under Hidden utilities in the UI kit.

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.
  • A link can be included. For example, Select a role for this admin. Learn more about roles.
    • Use an external link icon when necessary.
  • 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

If using the inline variant, the purpose of the input with a hidden label must be made clear in some other way contextually. In these cases, consult with the Odyssey team for an accessibility review.

  • In code, the label prop is still required. The label will be made accessible to screen reader text.
  • An HTML label element will still be rendered but visually hidden.

 

Figma: Autocomplete