HomeGetting StartedColor SystemTypographySpacingIconographyLayoutInstallationUsageAngularBlazorReactSvelteVueThemingTypographyCustomizationCSS-Only ComponentsFormsIconsIllustrationsAccessibilityGlobal ConfigurationTailwind CSSSass LibraryForge MCP ServerDropdown OptionsFocus Indicator ClippingAll componentsButtonButton AreaChipFloating Action ButtonIcon ButtonSplit ButtonAutocompleteButton ToggleCalendarCheckboxChip FieldColor PickerDate PickerDate Range PickerFile PickerLabelRadioSelectSliderSwitchText FieldTime PickerApp BarApp LauncherDrawerMenuPaginatorSkip LinkStepperTabsView SwitcherAccordionApp LayoutCardDividerExpansion PanelScaffoldSplit ViewStackStructured CardToolbarBadgeBannerBusy IndicatorCircular ProgressDialogInline MessageLinear ProgressPage StateSkeletonToastTooltipAvatarIconKeyLabel ValueListMeterSecretTableTimelineTimestampTreeKeyboard ShortcutPopoverIntroductionColorTypographySpacingShapeBorderElevationLayeringAnimationUsageIcon LibraryBlocksRoadmapChangelogBlog

Autocomplete

Autocomplete components provide real-time typeahead suggestions as users type in a text field.

Overview

Autocomplete enhances text input fields by providing dynamic suggestions as users type. It can be applied to various input components including single selects, multi-selects, and search fields to help users quickly find and select options from large datasets. The component filters and displays relevant suggestions based on the user’s input, reducing typing effort and improving accuracy.

Usage

forge-autocomplete wraps a text field and filters a list of options as the user types, through mode, multiple, debounce, and emptyMessage. Use it when a dropdown has too many options to scan comfortably; for a short, finite list, a select is simpler and doesn’t require typing.

Rules

Do
Use autocomplete when a dropdown has more options than a user can scan at a glance.Use when users might not know exact option names and need suggestions to guide their selection.Debounce keystrokes so filtering doesn't run on every character against a large data set.Set a clear empty-message so a no-results state doesn't look broken.Give the field a visible label, and use helper text to describe what it searches.
Don't
Don't use autocomplete for a short, finite list of options — use a select instead.Don’t use lengthy or unclear hint text that doesn't set proper expectations.Don't leave the field without hint text; a blank autocomplete is ambiguous.Don't overload the suggestion list with extra information — keep each option lightweight.

Modes

mode has two values: default (the common case) manages selection state for you as a form control. stateless doesn’t track a selection at all — use it when you just want the typing/filtering behavior and intend to handle selection yourself.

Initial value

Pre-populating a bound value on load needs the matching option available to show its label, not just the raw value. Either pass the full IOption object (value and label) to the value property directly, or return it from the filter callback’s second parameter — the autocomplete calls the callback with that parameter specifically when it can’t find a matching option already in its current list, so you can fetch it from wherever the rest of your options come from.

Basic filtering

Wrap a forge-text-field (typically with popover-icon and show-clear) in a forge-autocomplete to filter its dropdown options as the user types.

A text field filters its dropdown options as the user types.

Infinite scroll

Set observe-scroll to fire forge-autocomplete-scrolled-bottom as the user nears the bottom of the dropdown, so more options can be appended with appendOptions() instead of loading the entire set up front.

observe-scroll fires an event near the bottom of the dropdown to load more options.

Multi-select

Set multiple to let a user select more than one option instead of replacing the previous selection.

Multiple lets a user select more than one option.

Empty state

Set emptyMessage to show custom text in the dropdown when no options match the current filter.

An empty-message shows when no options match the filter. Search for something not in the list to see the empty state

Autocomplete components provide real-time typeahead suggestions as users type in a text field. Use autocompletes to help users quickly find and select from a list of options, improving form usability and data accuracy.

import "@tylertech/forge/autocomplete";
Properties
PropertyAttributeTypeDefaultDescription
modemode`${AutocompleteMode}`'default'Gets/sets the interaction mode.
multiplemultiplebooleanfalseGets/sets the multi-select state.
value—any—Gets/sets the value.
debouncedebouncenumber500Gets/sets the debounce delay (milliseconds) for keyboard events.
filterOnFocusfilter-on-focusbooleantrueGets/sets filter on focus settings which controls whether the dropdown displays automatically when focused.
filterFocusFirstfilter-focus-firstbooleantrueGets/sets whether the first option in the dropdown will be focused automatically when opened or not.
selectFirstOptionOnBlurselect-first-option-on-blurbooleanfalseDetermines whether the first available option should be selected automatically when blurring mid-filter.
allowUnmatchedallow-unmatchedbooleanfalseControls whether unmatched text entered by the user will stay visible an option in the dropdown is not found.
popupTargetpopup-targetstring—Gets/sets the selector that will be used to find an element to attach the popup to. Defaults to the input element.
filterText—string—Gets/sets the filter text. Setting the filter text only applies when allowUnmatched is enabled.
optionBuilder—AutocompleteOptionBuilder | null | undefined—Sets the option builder callback that will be executed when building the option list in the dropdown.
filter—AutocompleteFilterCallback | null | undefined—Sets the filter callback that will be executed when fetching options for the autocomplete dropdown. The callback is also invoked to resolve the display label for an already-selected value (e.g. on initialization, or via `forceFilter()`) by calling it with an empty `filterText` and the current `value` as its second argument. Implementations must handle this case by returning the matching option(s) for `value`, or the selected text will fail to resolve and appear blank.
selectedTextBuilder—AutocompleteSelectedTextBuilder—Sets the selected text builder callback that will be executed when getting the selected text.
openopenbooleanfalseControls the open state of the dropdown.
matchKeymatch-keystring | null | undefined—Gets/sets the property key to match the value to an option.
isInitialized—boolean—Returns whether the component has been initialized or not yet.
popupElement—HTMLElement | null—Gets the currently active popup element when the dropdown is open.
beforeValueChange—(value: any) => boolean | Promise<boolean>—Sets the callback to be executed when the user selects an option, before the UI is updated to allow for validation.
emptyMessageempty-messagestring | null | undefined—Gets/sets the message displayed when the filter returns no results.
emptyStateBuilder—AutocompleteEmptyStateBuilder | null | undefined—Sets the callback to build custom empty state content when the filter returns no results.
popupClassespopup-classesstring | string[]—Gets/sets the list of classes to apply to the popup element.
popupHeaderBuilder—ListDropdownHeaderBuilder—Gets/sets the callback function for generating header content within the popup.
popupFooterBuilder—ListDropdownFooterBuilder—Gets/sets the callback function for generating header content within the popup.
syncPopupWidthsync-popup-widthbooleanfalseGets/sets whether the popup width is synchronized with the popup target width.
optionLimitoption-limitnumber0Gets/sets the maximum number of options to display in the dropdown.
observeScrollobserve-scrollbooleanfalseControls the observation of scroll events on the dropdown.
observeScrollThresholdobserve-scroll-thresholdnumber0The number of pixels from the bottom to trigger the scroll bottom event. Only applicable if `observeScroll` is true.
constrainPopupWidthconstrain-popup-widthbooleantrueGets/sets whether the popup width will be constrained to a max width of the viewport width (default: `100vw`).
wrapOptionTextwrap-option-textbooleanfalseGets/sets whether the options will wrap their text or not. This only applies if `constrainPopupWidth` is `true`, if there is an explicit width set via CSS.
popoverPlacementpopover-placementOverlayPlacement'bottom'Gets/sets the placement of the popover.
popoverOffsetpopover-offsetIOverlayOffset—Gets/sets the offset of the popover.
popoverFlippopover-flipOverlayFlipState'auto'Gets/sets the flip state of the popover.
popoverShiftpopover-shiftOverlayShiftState'auto'Gets/sets whether the popover should shift to fit within the viewport.
popoverFallbackPlacementspopover-fallback-placementsPositionPlacement[] | null—Gets/sets the fallback placements of the popover.
Events
NameTypeDescription
forge-autocomplete-changeCustomEvent<any>Fired when the value changes.
forge-autocomplete-selectCustomEvent<IAutocompleteSelectEventData> Fired when an option is selected. Only applies when in "stateless" `mode`.
forge-autocomplete-scrolled-bottomCustomEvent<void>Fired when the dropdown is scrolled to the bottom. Only applies when `observe-scroll` is enabled.
Methods
NameReturnsDescription
appendOptions(options)voidAdds options to the dropdown while it is open. Has no effect if the dropdown is closed.
openDropdown()voidOpens the dropdown.
closeDropdown()voidCloses the dropdown.
forceFilter(opts)voidForces the filter callback to be executed to update the current selection state with new options. This invokes the `filter` callback with the current `value` (and an empty filter text) so it can resolve and return the matching option(s), allowing the selected text to be updated to their label.

Keyboard shortcuts

Key Action
Down / Arrow Down Opens the dropdown and activates the first option
Arrow Up / Arrow Down Moves through the list of options
Enter Selects the active option
Home / End Jumps to the first or last option
Tab Single-select: selects the active option and closes the dropdown
Escape Closes an open dropdown
Backspace / Delete Edits the input’s text; clears a single-select value when the input is empty

Screen reader behavior

The input automatically receives role="combobox", aria-live, and aria-owns. You’re still responsible for labeling it yourself — with a <label>, aria-label, or aria-labelledby — the component doesn’t provide one for you.

Verify you can tab into the autocomplete and reach every option in the dropdown using only the keyboard.

Loading Forge chat…