Components/Form
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/atlasaddressinput
AtlasAddressInput allows users to search for an address with a built-in autocomplete service.
To use this component you must install the following peer-dependencies:
npm install @wix/ambassador @wix/ambassador-wix-atlas-service-web
<AddressInput/> which provides the UI only.Requests to Atlas must be authorized using an authorization header. Check out this Wix Doc about how to retrieve a signed instance in your environment.
Pass an authorization token to AtlasAddressInput using the token prop.
Adjust the component size using size prop. It supports 3 sizes:
large - use it in onboarding flows, where input needs emphasis.medium (default) - use in all common cases.small - use in more dense and narrow layouts.Style the component using border prop. It supports 4 styles:
round (default) - use it when input acts as a filter.standard - use it in a form.bottomLine - use as a title which can be edited on the click.none - use in Content Manager's spreadsheet cell.Control component status using status prop. It supports 3 states:
error - use it to highlight invalid input value.warning - use it to highlight value that can't be validated.loading - use it to indicate a delayed response from the server.Add text that explains the status or what action the user should take with the statusMessage prop.
Showing the status message inline, directly below the input is preferred in all default cases.
<FormField/> and add the statusMessage.statusMessage prop.View more inline status message examples in <FormField/>.
Disable all input interactions with disabled prop. Use it to highlight unavailable functions.
Control whether to show a clear button with clearButton prop. It allows you to clear the field quickly when a value is optional.
Control options list layout with optionLayout prop. It supports 2 layouts for main and secondary labels:
single-line (default) - use it to display labels side by side.double-line - use it to stack labels vertically.Add supportive info to an options list in defined affix areas:
optionPrefix - use the location icon by default. Override only in cases where more specific context is needed, i.e. defining work address.optionSuffix - use it to provide extra info about address.Control the message displayed in the dropdown layout when no results are found via noResultsText
Translate search results per country by providing language and locale details.
language prop.locale prop.Define custom address formatting using onSelect callback that provides a getAddress function to fetch a Wix Address Object from Atlas.
This example displays a post code along with the address.
| Name | Type | Default | Description |
|---|---|---|---|
autoSelect | boolean | — | Specifies whether input is auto selected on focus. |
baseUrl | string | — | |
border | "none" | "standard" | "round" | "bottomLine" | — | Control the border style of an input. |
clearButton | boolean | true | Displays a clear button (X) on a non-empty input. |
clearButtonAriaLabel | string | — | Aria label for the clear button. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in the tests. |
debounceFn | <T extends (...args: any[]) => any>(callback: T, debounceMs: number) => (...args: Parameters<T>) => unknown | — | Allows passing a custom debounce function (default: lodash debounce). Receives the callback to debounce and the wait in ms, and returns a debounced function with the same parameters. |
debounceMs | number | — | Fetch predictions debounce in milliseconds (default: 200) |
disabled | boolean | — | Specifies whether input is disabled. |
enterKeyHint | "search" | "enter" | "done" | "go" | "next" | "previous" | "send" | — | Sets the label of the virtual keyboard's enter key on touch devices. |
initialValue | string | — | Sets the initial input value. |
inputmode | string | — | Sets the native inputmode attribute, which picks the virtual keyboard on touch devices. Supported values are none, text, decimal, numeric, tel, search, email and url. |
language | string | — | Sets the language to pass to the Atlas Service. Use the language code, for example 'en'. |
locale | string | — | Sets the locale to pass to the Atlas Service. Locale consists of language code and country code separated by a dash, for example 'en-us'. |
noResultsText | ReactNode | — | Sets the message to show in a dropdown when no results are found. |
onBlur | FocusEventHandler | — | Defines a standard input onBlur callback. |
onChange | ChangeEventHandler | — | Defines a callback function which is called every time input value is changed. |
onClear | () => void | — | Defines a handler for getting notified upon a clear event. When passed, it displays a clear button in the input. |
onError | (error: AmbassadorHTTPError<any>) => any | — | Defines a handler for prediction fetching errors. Receives the HTTP error object of the failed request. |
onFocus | (e?: FocusEvent<HTMLInputElement, Element> | undefined) => void | — | Defines a standard input onFocus callback. |
onSelect | (option: DropdownLayoutValueOption, getAddress: GetAddress) => void | — | Defines a callback function which is called whenever a user selects a different option in the list. |
optionLayout | "single-line" | "double-line" | — | Sets the layout of mainLabel and secondaryLabel. The possible options can be either side by side or vertically stacked. |
optionPrefix | ReactNode | — | Pass any component to show as the prefix of the option, e.g., text, icon. |
optionSuffix | ReactNode | — | Pass any component to show as the suffix of the option, e.g., text, icon, button. |
placeholder | string | — | Sets a placeholder message to display. |
popoverProps | PopoverCommonProps | — | Allows to pass common popover props. |
ref | null | string | (instance: AtlasAddressInputImperativeActions | null) => void | RefObject<AtlasAddressInputImperativeActions> | — | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). |
selectOnSubmit | boolean | — | Specifies whether to trigger onSelect handler when performing a Submit-Action (Enter or Tab key down). If set to true, onSelect will be called with the following params: option: an option with a label set to the input value. getAddress: function for retrieving additional place details uses Atlas's search function to return the closest result to the input value This is useful when looking for locations for which Atlas doesn't give suggestions - for example: Apartment/Apt. |
size | "small" | "medium" | "large" | — | Controls the size of the input and its dropdown options. Default value: medium. |
status | "error" | "warning" | "loading" | — | Specify the status of a field. Mostly used for "loading" indication upon async request calls. |
statusMessage | ReactNode | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
token | string | — | |
value | string | — | Sets a value to display (controlled mode). |
Import the driver matching your test environment:
| Method | Description |
|---|---|
getInputValue | Returns value of the input |
enterText | Enters given text to input |
clickClear | Clicks on the clear button to clear input text |
isDisabled | Checks if input is disabled |
clickAtOption | Clicks an option at given index |
clickAtOptionWithValue | Clicks an option with a given value |
isLoading | Whether loader is shown |
clickInput | Clicks on input |
getAmountOfItems | Gets amount of dropdown items |
getItemMainLabelAt | Gets item main label text at given index |
getItemSecondaryLabelAt | Gets item secondary label text at given index |
pressEnter | Press enter on address input |
isFocused | Checks whether the address input is focused |
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