Components/Form/AutoCompleteWithLabel
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/autocompletewithlabel
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.
<Autocomplete/> instead.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
Explain the status with `statusMessage` prop.
It only works when `status` is set to `error`.
Disable all input interactions with `disabled` prop. Use it to highlight unavailable functions.
Explain the field value with additional information added to the `suffix` area. This prop accepts text, icons and even buttons.
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.
Control container size with `maxHeightPixels` prop. Use it to restrict the height of longer lists of options.
The autocomplete selection only be used in a Premium Checkout form.
| Name | Type | Default | Description |
|---|---|---|---|
ariaLabel | string | — | Define a string that labels the current element in case where a text label isn't visible on the screen. |
autocomplete | string | 'on' | Sets the value of the native autocomplete attribute, for example off or email. |
autoFocus | boolean | — | Focus the element on mount (standard React input autoFocus). |
dataHook | string | — | Sets a default value for those who want to use this component un-controlled. |
disabled | boolean | — | Specifies whether input should be disabled or not. |
label | string | '' | Defines a value label to show inside of a field. |
maxHeightPixels | string | number | — | Sets the maximum height of the dropdownLayout in pixels. |
maxLength | number | — | Sets the maximum number of characters that can be entered into a field. |
name | string | — | Reference element data when a form is submitted. |
native | boolean | — | Indicates whether to render using the native select element. |
onBlur | FocusEventHandler | — | Defines a standard input onBlur callback. |
onChange | ChangeEventHandler | — | Defines a standard input onChange callback. |
onFocus | FocusEventHandler | — | 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. |
options | DropdownLayoutOption[] | — | Specify an array of options to display in the dropdown list. |
placeholder | string | — | Sets a placeholder message to display. |
status | "error" | "warning" | "loading" | — | Specify the status of a field. |
statusMessage | ReactNode | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
suffix | ReactNode[] | — | Pass a component you want to show as the suffix of the input, e.g., text string, icon. |
type | string | — | Specifies the type of <input/> element to display. Default is text string. |
value | string | number | — | Value of rendered child input. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
getLabelText | Gets label text |
getValue | Gets input value |
enterText | Enters given text to input |
clickAtOption | Clicks an option at given index |
clickAtOptionWithValue | Clicks an option with a given value |
clickMenuArrow | Clicks the menu arrow |
isDisabled | Checks if input is disabled |
blur | Triggers blur event on the input element |
hasError | Checks whether there's a visible error icon |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
Last updated: 22 October 2026