Components

Typeahead

Form element for text input with a dropdown to show relevant or suggested values and highlights matching values as the user enters characters into the input field

 

Overview

  • Available sinceQuebec
  • A11Y WCAG 2.1 AA

Typeahead is a component that predicts and suggests possible matches as users type into an input field. It makes it easier for users to find what they’re looking for by presenting a list of options to choose from as they type.

ServiceNow link
Typeahead code documentation

UIB and developer guidance

Figma link
Typeahead Figma component

Figma library with components for designing Workspace.

Loading playground

When to use

Use typeahead when users need to choose from a large set of options, and you want to facilitate faster and more accurate input. It is particularly useful for search boxes, tagging systems, or scenarios using predictive suggestions.

When not to use

Don’t use typeahead for situations where the list of options is limited, and users can easily browse or select from a few choices. For a small, manageable set of options, use a dropdown or radio buttons instead.

Anatomy

typeahead anatomy
  1. Label: Title of the input field; a label must be present for accessibility, either as the component's label element or external to the component
  2. Required indicator (optional): Field decorator that indicates if a field is required
  3. Information button (optional): Opens a popover and shows the field helper text
  4. Label-inline slot (optional): An available slot for an additional label icon
  5. Label-end slot (optional): An available slot at the end of the label line
  6. Input field slot (optional): Displays additional field decorators or actions; a maximum of three can be added
  7. Section header (optional): Header inside the dropdown that displays additional information about the list items
  8. List item label: The main information in a list item; this label fills the field when that list item is selected
  9. List item sub-label (optional): Supplemental information that is associated with the list item label; provides users with more information about the list item
  10. Avatar (optional): The avatar associated with the list item can be displayed; used when avatar is relevant to the dropdown options
  11. Dropdown list: Displays a list of selectable options to fill the field
  12. Input field: Space where the user enters text; a dropdown opens and responds dynamically as the user adds text

Usage

Learn about typeahead and find out how to use it in your design. Typeahead should be used to help a user quickly fill an input field by narrowing down many results of a similar type.

Form field

Typeahead can be used as a single form field or part of a group of related form fields.

typeahead used in form field

Variants

Learn about the variants of typeahead.

Types

This usage guidance is for the typeahead component. For use cases that require the option to fill an input field with more than one result, see usage guidance for typeahead multi.

Sizes

Typeahead has the following sizes: small (sm) and medium (md). Choose a size that fits with your display and complements the surrounding content.

Small

Use the small size for areas that have limited space. The font size is reduced compared to the default medium size.

Small text variant.

Medium

Use the medium size alongside similarly sized components and content.

Note: Medium is the default size for typeahead.

Medium text variant.

Configurations

Learn how to customize typeahead by configuring the available properties.

Slots

The typeahead input field slot can appear at the beginning or end of an input field. You can add up to three field decorators that are associated with the typeahead input field.

typeahead field decorator

Typeahead input field with a preview button iconic. After filling the input field, the user can select this field decorator to view the profile associated with the name in the "Assigned to" field.

input field slot on the right side

This example shows an AI icon used to indicate the value was AI generated.

The label has an end and in-line slot for additional information. The label-end slot is available at the end of the label line. The label-inline slot is available immediately after the field helper icon. You can add anything to the label-inline slot, but icons are the most appropriate use for this slot.

input field slot at the beginning of a form input field.

This example shows a color label with optional icon to indicate status or category.

input field slot at the beginning of a form input field.

This example shows a device type indicator in the label-inline slot.

Placeholder text

You can add unique placeholder text for each input field. Placeholder text should be a hint that supplements the label. This could be the suggested format for the expected input or guidance on how to complete the field. The placeholder text disappears when the user enters the first character.

typeahead placeholder text

Optional indicator

You can configure an input field as “optional” to indicate the user isn't required to select a value in this field to complete the form. Optional fields will display "(Optional)" text next to the form label.

Note: Don't use this indicator in conjunction with the required field indicator.

typeahead optional field indicator

Required indicator

You can configure an input field as required with an asterisk indicator after the form label. The user must enter a value in a required field to complete the form. When the user hovers over the asterisk, a tooltip appears and displays "Required."

Note: Don't use this indicator in conjunction with the optional indicator.

typeahead required field indicator

Read-only field

You can configure an input field as read-only to indicate that the user can’t modify the value in this field. However, users can select and copy the values in the input field. If the input field doesn't contain a value, it displays an em dash (—) to denote an empty value. When the user hovers over the field a tooltip appears and displays “Read-only.”

Disabled field

You can disable an input field which makes the field unavailable for users to interact with.

Invalid field

Use to show when the user enters an invalid input. Typically, it indicates an error has occurred.

Field helper text

You can add an information button iconic next to the form label. Use the field helper text to display information needed for guiding users on how to complete the field. This can include formatting guidance, requirements, or an explanation of the input field's purpose. The helper text will display in a popover when the user selects the information icon.

See usage guidance for popover

typeahead field helper

Field layout

You can configure the field layout to be horizontal or vertical. The default field layout is “vertical”.

Example of horizontal layout

Field messages

You can configure custom messages to appear beneath the typeahead input field. These provide users with error messages, helpful suggestions, guidance, or information for completing the input field.

Message type Example
Error now-typeahead
Warning now-typeahead
Positive now-typeahead
Field information now-typeahead
Suggestion now-typeahead

Auto-focus

Use this configuration to automatically place focus on an input field when a user opens the page.

Search behavior

You can choose a type of search behavior for your use case. The chosen search behavior instructs the dropdown how to respond as the user enters text into the input field. Typeahead search behavior: managed, initial, and contains.

The default search behavior is "managed." In this configuration type, the dropdown list is not filtered, allowing the user to view the full list as the user enters characters into the input field.

typeahead managed search behavior

When search behavior is in "managed," the full list is shown while matching values are highlighted.

The second type of search behavior is "initial." This configuration type returns list items whose initial characters match the input field text entered by the user. The matching characters are highlighted.

typeahead initial search behavior

The third type of search behavior is "contains." This configuration type returns list items that contain any of the user input characters in the list item.

typeahead contains search behavior

Section header

Section headers can be configured into the dropdown to add clarity and organization to the dropdown list items.

typeahead section header

In this example, the section header adds clarity by keeping a count of the list items.

Item sub-labels

The dropdown list items can be configured to show supplemental information.

typeahead secondary values

In this example, the dropdown list items display state names. Sub-labels are added to specify the city.

Avatar

The dropdown list items can be configured to show associated avatars. Avatar should only be used if it is relevant to the list items.

typeahead avatar

In this example, avatars provide visuals that help the user select the right list item.

Behavior

Learn how typeahead behaves when the display changes or a user interacts with the component.

States

The typeahead input field has the following states: default, hover, focus, read only, disabled, and invalid.

State Example
Default now-typeahead
Hover now-typeahead
Focus now-typeahead
Read-only now-typeahead
Disabled now-typeahead
Invalid now-typeahead

Disabled state

Users can’t interact with an input field when it’s disabled.

Read-only state

Users can't interact with any elements in the input field when the field is in a read-only state with the exception of selecting and copying the value in the field. If the input field doesn't contain a value, it displays an em dash (—) to denote an empty value.

Invalid state

In an invalid state, the indicator and label of a required input field appear in red. If the label includes either a required indicator or an optional indicator, it also appears in red. This can be triggered if the field is required and not filled in.

A form field message can appear below the input field to help communicate what has caused the error. To learn more about types of form field messages, see usage guidance for input field.

typeahead error state with error message

In this example, the input is invalid and a message is provided to help the user resolve the error.

Dropdown list has the following states: default, hover, focus, selected, and disabled.

State Example
Default now-typeahead
Hover now-typeahead
Focus now-typeahead
Selected now-typeahead
Disabled now-typeahead

Highlighted search value

The highlighted search value is a visual indication in the result list. When the user types something in the input field, any matching values from the dropdown list will be highlighted.

typeahead error state with error message

Responsive behaviors

Typeahead inherits the width of its container and resizes with the container.

Input field overflow

If text in the input field exceeds the width of the container or content area, the leftmost characters fall out of view in order to accommodate new characters.

Interactions

Users can interact with typeahead through the input field and dropdown list. This includes any field decorators.

Selection

A user can select the input field to open the dropdown list and use typeahead to filter list items. As the user types, the dropdown list responds dynamically in accordance with the configured search behavior. Once the user selects an item, the dropdown collapses.

Note: A user can choose to enter a full list item into the input field to generate a complete match in the dropdown list. If this method is used, the user can select outside the input field to close the dropdown and fill the input field with the chosen list item.

Label truncation

The label will truncate when it exceeds the input field width or when the label indicators prevent the full label from displaying.

Dropdown list text wrap

label truncation with ellipsis

In this example, the required field indicator and information icon prevent the label from fully displaying. Therefore, the label truncates with an ellipsis, and the full label is available in a tooltip on hover.

Dropdown section header text, list items and sub-labels will wrap upon reaching the end of the panel.

typeahead truncation

In this example, the section header text and third list item exceed the width of the dropdown and wrap into the next line. Above, the input field accommodates overflowing text.

Design recommendations

Learn how to apply typeahead in your design.

typeahead used correctly to narrow down a long list
Do

Do use typeahead when there are many list items to select from and filtering by typing is more efficient than searching through the entire list to select an option.

typeahead should not be used for a small list
Don’t

Don't use typeahead if there are only a few distinct list items to select from. Instead, use select dropdown.

typeahead used correctly for a similar result type
Do

Do use typeahead to help users select an item from a list of related items.

typeahead used incorrectly for open-ended result types
Don’t

Don't use typeahead if the items in the dropdown list cannot be relevantly grouped. For fields that requires more open-ended results, use an input field without typeahead.

UI text guidelines

Typeahead uses the input component. These are some recommendations for using text within input.

Label

  • Use a label that describes the expected input or a question you’re asking the person

Form field messaging

  • Informational message
    • Use clear and concise language to help the person fill out the input
      • For example, “Only use letters and numbers in your username.”
  • Warning message
    • Include information that helps the person understand any consequences or next steps
    • Use present tense since this message shows up before any input.
      • For example, “Credit card information will only be used for purchasing purposes.”
  • Error message
    • Avoid blaming the person. Instead, tell them what happened and how they can fix it.
    • Use past tense since this message shows up after the person enters something
      • For example, “Someone used this name already. Try entering a different name.”

Field helper text

  • Provide additional information to help the person understand the field and what they're expected to input
  • Avoid putting critical information in an Information icon because they aren’t always visible

Placeholder text

  • Use sparingly because it will disappear once the person puts their cursor in the input field
  • Format placeholder text as an example of what should go in the input or a brief description of how to complete the field
    • For example, “Enter what has changed in this version of the app.”

Usability

Typeahead complies with all internationalization and accessibility requirements.

Internationalization

When the display translates to a right-to-left (RTL) language, the contents of the typeahead input field and dropdown will flip sides. This includes text and field decorators.

typeahead alignment flips for right to left languages

Accessibility

Learn how to access the actionable elements of typeahead through keyboard interactions and screen readers.

Keyboard interactions

  • Tab or shift + tab: Moves between the typeahead field and any interactive elements in the standard tab order

When the focus is in typeahead input field:

  • Enter: Toggles the dropdown open or closed
  • Arrow down: Opens the dropdown

When the focus is in the dropdown:

  • Arrow down: Moves focus to next list value
  • Arrow up: Moves focus to previous list value or closes the dropdown, if the focus was on the first list value in the dropdown
  • Enter: Selects the focused list value by populating the value in the input field and closes the dropdown
  • Escape: Collapses the dropdown and moves focus to the input field
  • Tab: Collapses the dropdown and moves focus to the next interactive element in the tab order
  • Home: Moves focus to the first option and selects it
  • End: Moves focus to the last option and selects it