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.
When to Use
- Free-text entry where suggestions speed up input
- Searching a large or remote dataset that loads asynchronously
- Inputs where users may type a value that isn’t in the list
When not to use
- Selecting from a fixed set of options where a value is required — use Select Field instead
- Searching or filtering content on the page rather than completing a field — use Search Field
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.Last modified on June 12, 2026
