Typeahead Text Field

Beta FeatureThis feature is currently in beta, and needs to be imported from @servicetitan/anvil2/beta.While we hope to minimize breaking changes, they may occur due to feedback we receive or other improvements. These will always be documented in the changelog and communicated in Slack.Please reach out in the #ask-designsystem channel with any questions or feedback!

import { TypeaheadTextField } from "@servicetitan/anvil2/beta";

const FRUIT = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Cherry", value: "cherry" },
];

function App() {
  return (
    <TypeaheadTextField
      label="Fruit"
      placeholder="Start typing..."
      loadOptions={(search) =>
        FRUIT.filter((f) =>
          f.label.toLowerCase().includes(search.toLowerCase()),
        )
      }
    />
  );
}

export default App;

Anatomy

Typeahead Text Field consists of three primary elements that work together to surface suggestions as the user types.

Text input - Accepts free-form text and drives the search
Loading indicator - A spinner in the suffix slot that signals suggestions are being fetched
Suggestion menu - A popover listbox of matching options anchored to the input

Options

Typeahead Text Field supports the following configurations.

Sizes

Typeahead Text Field inherits the three Text Field sizes. Match the size to the density of the surrounding form.

import { TypeaheadTextField, Flex } from "@servicetitan/anvil2/beta";

const loadOptions = (search) => [];

function App() {
  return (
    <Flex gap="6" direction="column">
      <TypeaheadTextField size="small" label="Small" loadOptions={loadOptions} />
      <TypeaheadTextField size="medium" label="Medium" loadOptions={loadOptions} />
      <TypeaheadTextField size="large" label="Large" loadOptions={loadOptions} />
    </Flex>
  );
}

export default App;

Size	Height
Small	32px
Medium	40px
Large	48px

Empty focus

By default the menu opens only once the input holds a value. Enable opening on focus while empty for “show all” experiences where users browse options without typing first.

Behavior

Typeahead Text Field responds to typing, focus, and selection to keep suggestions relevant and the layout stable.

Suggestions

As the user types, the field requests matching options and renders them in the menu. Requests are debounced so suggestions refresh once typing pauses rather than on every keystroke. Stale responses from slower requests are discarded, so the menu always reflects the latest input.

Loading

While options resolve, a spinner appears in a fixed-width suffix slot. The slot reserves its space at all times, so the field never reflows as the spinner appears or the value changes.

Selection

Choosing a suggestion fills the input with the option label, closes the menu, and returns focus to the input. Highlight the field whenever its value comes from a selected suggestion, so users can distinguish a confirmed choice from free-typed text. Clear the highlight as soon as the user edits the value, since an edit means the text no longer matches the suggestion.

Empty and loading states

When a request returns no matches, the menu shows a “No suggestions found” message. While the first set of options loads, it shows a “Loading…” message. Both messages are informational and cannot be selected.

Usage Guidelines

Use the Typeahead Text Field when users enter free-form text that benefits from suggestions, such as addresses, tags, or product names.

Standard	Requirement
DoFree-text entry with suggestions	Free-text entry where suggestions speed up input
DoLarge or remote async datasets	Searching a large or remote dataset that loads asynchronously
DoValues outside the list	Inputs where users may type a value that isn’t in the list
Don’tFixed required selection	Selecting from a fixed set of options where a value is required. Use Select Field instead.
Don’tPage search or filtering	Searching or filtering content on the page rather than completing a field. Use Search Field instead.

Alternatives

Typeahead Text Field vs Select Field

Use Select Field when the user must choose a value from a defined set of options. Use Typeahead Text Field when the input accepts free-form text and suggestions are an aid rather than a constraint. The clearest reason to choose Typeahead Text Field is when a suggestion shows more information than belongs in the field itself. Select Field writes the full selected option into its trigger, so any supporting detail shown in the list also lands in the field. Typeahead Text Field keeps the suggestion display and the field value separate: each suggestion can show rich detail, while only the portion relevant to the field is written to the input. For example, an address field can present full formatted addresses in the menu — street, city, state, and postal code — while writing only the street line to the field. The remaining details populate their own fields from the selected suggestion, so each field holds only what’s relevant to it.

Content

Content within the Typeahead Text Field should set clear expectations for what to type and what suggestions represent. Write placeholder text that describes the expected input, and keep suggestion labels concise and scannable.

Keyboard Interaction

Users can navigate the Typeahead Text Field using standard keyboard controls.

Key	Action
Down Arrow	Opens the menu and moves focus to the first suggestion
Up / Down Arrow	Moves focus between suggestions, wrapping at the ends
Enter	Selects the focused suggestion
Escape	Closes the menu and returns focus to the input
Tab	Closes the menu and continues the tab order

Accessibility

The input is exposed as a combobox that controls the suggestion listbox, with its expanded state announced to assistive technology. When suggestions load asynchronously, the loading message is announced politely so users learn when results arrive. For more guidance on form field labels and context, see input field context association best practices.

Anvil2 Web

Resources

Typeahead Text Field – Design

Anatomy

Options

Sizes

Empty focus

Behavior

Suggestions

Loading

Selection

Empty and loading states

Usage Guidelines

Alternatives

Typeahead Text Field vs Select Field

Content

Keyboard Interaction

Accessibility

​Anatomy

​Options

​Sizes

​Empty focus

​Behavior

​Suggestions

​Loading

​Selection

​Empty and loading states

​Usage Guidelines

​Alternatives

​Typeahead Text Field vs Select Field

​Content

​Keyboard Interaction

​Accessibility

Anatomy

Options

Sizes

Empty focus

Behavior

Suggestions

Loading

Selection

Empty and loading states

Usage Guidelines

Alternatives

Typeahead Text Field vs Select Field

Content

Keyboard Interaction

Accessibility