AddressInput

Components/Form

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

Overview

Copy

Address input allows users to enter a location address. This component provides UI definition only and requires an address provider to be specified from the product side.

Do

  • Use it to search for a location.
  • Use it to enter addresses that must be validated before they are submitted.
  • Use it as a UI element together with a required address provider passed from the side.

Don't

  • Don't use it as a standalone solution. Use <AtlasAddressInput/> instead.

Feature examples

Size

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 dense and narrow layouts.
Copy

Border

Style the component using border prop. It supports 4 styles:

  • round (default) - use it when input acts as a data filter.
  • standard - use it in forms.
  • bottomLine - use as a title which can be edited on the click.
  • none - use in Content Manager's spreadsheet cell.
Copy

Status

Control component status using status prop. It supports 3 states:

  • error - use it to highlight an invalid input value.
  • warning - use it to highlight a value that can't be validated.
  • loading - use it to indicate a delayed response from the server.
Copy

Status message

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.

  • To add an accessible inline message, wrap the component in a <FormField/> and add the statusMessage.
  • To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop.

View more inline status message examples in <FormField/>.

Copy

Disabled

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

Copy

Clear button

Control whether to show a clear button with the clearButton prop. It allows to clear the field quickly when a value is optional.

Copy

No results message

Control the message displayed in the dropdown layout when no results are found via noResultsText.

Copy

Options layout

Control an options list layout with optionLayout prop. It support 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.
Copy

Prefix

Specify icons on the left side with prefix prop or choose not to show it by setting prefix to null.

By default, <LocationIcon /> is displayed.

Copy

Common use case examples

Custom options list

Use list item builders to build a custom options list layout.

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoSelectboolean—Specifies whether input is auto selected on focus.
border"none" | "standard" | "round" | "bottomLine"—Control the border style of an input.
clearButtonbooleantrueDisplays a clear button (X) on a non-empty input.
clearButtonAriaLabelstring—Aria label for the clear button.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—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.
initialValuestring—Sets the initial input value.
inputmodestring—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.
noResultsTextReactNode—Sets the message to show in a dropdown when no results are found.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onChangeChangeEventHandler—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.
onFocus(e?: FocusEvent<HTMLInputElement, Element> | undefined) => void—Defines a standard input onFocus callback.
onManuallyInputManualInputFnSignature—Defines a callback function which is called when user performs a submit action. Submit-Action triggers are: "Enter", "Tab".
onSelect(option: DropdownLayoutValueOption) => void—Defines a callback function which is called whenever a user selects a different option in the list.
optionsDropdownLayoutOption[]—Specify an array of options to render. When the option is an {optionProps}, the <AddressInput.Option/> component is rendered on behalf of the user.
placeholderstring—Sets a placeholder message to display.
popoverPropsPopoverCommonProps—Allows to pass common popover props.
refnull | string | (instance: AddressInputRef | null) => void | RefObject<AddressInputRef>—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).
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.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
valuestring—Sets a value to display (controlled mode).

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getInputValueReturns value of the input
enterTextEnters given text to input
clickClearClicks on the clear button to clear input text
isDisabledChecks if input is disabled
clickAtOptionClicks an option at given index
clickAtOptionWithValueClicks an option with a given value
isLoadingWhether loader is shown
clickInputClicks on input
getAmountOfItemsGets amount of dropdown items
getItemMainLabelAtGets item main label text at given index
getItemSecondaryLabelAtGets item secondary label text at given index
pressEnterPress enter on address input
isFocusedChecks whether the address input is focused
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.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 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.331.0 (2026-10-01) — 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.323.0 (2026-09-10) — 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.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.228.0 (2025-11-18) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.190.0 (2025-05-22) — maintenance release, no component-specific changes
  • 1.186.0 (2025-05-05) — maintenance release, no component-specific changes
  • 1.185.0 (2025-04-30) — maintenance release, no component-specific changes
  • 1.170.0 (2025-03-12) — maintenance release, no component-specific changes
  • 1.147.0 (2024-12-13) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.105.0 (2024-05-21) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?