AutoCompleteWithLabel

Components/Form/AutoCompleteWithLabel

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/autocompletewithlabel

Overview

Copy

AutoCompleteWithLabel allows users to select a single item from a predefined list of options. This component provides an editable input field for filtering the list and a built-in label.

Do

  • Use it in Wix Premium checkout form.

Don't

  • Don't use it in Wix Business Manager applications, use <Autocomplete/> instead.

Feature examples

Status

Control the component status using a `status` prop. It supports 2 states:
 - `error` - use it to highlight an invalid search keyword that has no matching results
 - `warning` - use it to highlight value that impacts the user or can't be validated

Copy

Status Message

Explain the status with `statusMessage` prop.

It only works when `status` is set to `error`.

Copy

Disabled

Disable all input interactions with `disabled` prop. Use it to highlight unavailable functions.

Copy

Suffix

Explain the field value with additional information added to the `suffix` area. This prop accepts text, icons and even buttons.

Copy

List item builders

Build custom layouts with:
 - `listItemSectionBuilder` - use it to group list items into sections by type. See ListItemSection for more details.
 - `listItemActionBuilder` - use it to add text buttons for related list actions, e.g., 'Manage categories'. See ListItemAction for more details.
 - `listItemSelectBuilder` - use it to build custom list designs. See ListItemSelect for more details.

Copy

List container height

Control container size with `maxHeightPixels` prop. Use it to restrict the height of longer lists of options.

Copy

Common use case examples

Checkout Form

The autocomplete selection only be used in a Premium Checkout form.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaLabelstring—Define a string that labels the current element in case where a text label isn't visible on the screen.
autocompletestring'on'Sets the value of the native autocomplete attribute, for example off or email.
autoFocusboolean—Focus the element on mount (standard React input autoFocus).
dataHookstring—Sets a default value for those who want to use this component un-controlled.
disabledboolean—Specifies whether input should be disabled or not.
labelstring''Defines a value label to show inside of a field.
maxHeightPixelsstring | number—Sets the maximum height of the dropdownLayout in pixels.
maxLengthnumber—Sets the maximum number of characters that can be entered into a field.
namestring—Reference element data when a form is submitted.
nativeboolean—Indicates whether to render using the native select element.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onChangeChangeEventHandler—Defines a standard input onChange callback.
onFocusFocusEventHandler—Defines a standard input onFocus callback.
onSelect(option: DropdownLayoutValueOption) => void—Defines a callback function which is called whenever user selects a different option in the list.
optionsDropdownLayoutOption[]—Specify an array of options to display in the dropdown list.
placeholderstring—Sets a placeholder message to display.
status"error" | "warning" | "loading"—Specify the status of a field.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
suffixReactNode[]—Pass a component you want to show as the suffix of the input, e.g., text string, icon.
typestring—Specifies the type of <input/> element to display. Default is text string.
valuestring | number—Value of rendered child input.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getLabelTextGets label text
getValueGets input value
enterTextEnters given text to input
clickAtOptionClicks an option at given index
clickAtOptionWithValueClicks an option with a given value
clickMenuArrowClicks the menu arrow
isDisabledChecks if input is disabled
blurTriggers blur event on the input element
hasErrorChecks whether there's a visible error icon
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.322.0 (2026-09-09) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.259.1 (2026-03-02) — maintenance release, no component-specific changes
  • 1.248.0 (2026-01-23) — fix: guard against undefined option in onSelect (#15833)
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.124.0 (2024-09-06) — maintenance release, no component-specific changes
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?