> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: AddressInput Component

## Article: AddressInput Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/address-input-component.md

## Article Content:

# AddressInput

_Components/Form_

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

## Overview

```jsx
() => {
  const predictions = [
    {
      id: 0,
      displayLabel: 'Home 2818 Saint Patrick Pl, Helena, AL, 35080',
      mainLabel: 'Home',
      secondaryLabel: '2818 Saint Patrick Pl, Helena, AL, 35080',
    },
    {
      id: 1,
      displayLabel: 'Work 512 4th St NE, Montgomery, MN, 56069',
      mainLabel: 'Work',
      secondaryLabel: '512 4th St NE, Montgomery, MN, 56069',
    },
  ];
  const options = predictions.map(addressInputItemBuilder);

  return (
    <Box align="center">
      <Box direction="vertical" width="30%">
        <AddressInput placeholder="Search places..." options={options} />
      </Box>
    </Box>
  );
};
```

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddressInput placeholder="Large" size="large" />
  <AddressInput placeholder="Medium" size="medium" />
  <AddressInput placeholder="Small" size="small" />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddressInput placeholder="Round" border="round" />
  <AddressInput placeholder="Standard" border="standard" />
  <AddressInput placeholder="Bottom Line" border="bottomLine" />
  <AddressInput placeholder="None" border="none" />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddressInput placeholder="Error" status="error" />
  <AddressInput placeholder="Warning" status="warning" />
  <AddressInput placeholder="Loading" status="loading" />
</StorybookComponents.Stack>;
```

#### 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/>`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For all default cases:</Text>
    <FormField status="error" statusMessage="This is an error message.">
      <AddressInput placeholder="See message below" />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For narrow layouts only:</Text>
    <AddressInput
      placeholder="Hover on status icon"
      status="error"
      statusMessage="This is an error message."
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Disabled

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

```jsx
<AddressInput placeholder="Disabled" disabled />;
```

#### 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.

```jsx
() => {
  const [value, setValue] = React.useState(
    '903  Wilmar Farm Road, Rockville, Maryland',
  );

  return (
    <AddressInput
      placeholder="Search for address..."
      value={value}
      onChange={(e) => setValue(e.target.value)}
      clearButton={true}
      onClear={() => setValue('')}
    />
  );
};
```

#### No results message

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

```jsx
<AddressInput value="Invalid search term" noResultsText="No results found" />;
```

#### 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.

```jsx
() => {
  const singleLineOptions = [
    addressInputItemBuilder({
      id: 1,
      displayLabel: 'Address 1 Country',
      mainLabel: 'Address 1',
      secondaryLabel: 'Country',
      optionLayout: 'single-line',
    }),
    addressInputItemBuilder({
      id: 2,
      displayLabel: 'Address 2 Country',
      mainLabel: 'Address 2',
      secondaryLabel: 'Country',
      optionLayout: 'single-line',
    }),
  ];
  const doubleLineOptions = [
    addressInputItemBuilder({
      id: 1,
      displayLabel: 'Address 1 Country',
      mainLabel: 'Address 1',
      secondaryLabel: 'Country',
      optionLayout: 'double-line',
    }),
    addressInputItemBuilder({
      id: 2,
      displayLabel: 'Address 2 Country',
      mainLabel: 'Address 2',
      secondaryLabel: 'Country',
      optionLayout: 'double-line',
    }),
  ];
  return (
    <StorybookComponents.Stack flexDirection="column">
      <AddressInput placeholder="Single Line" options={singleLineOptions} />
      <AddressInput placeholder="Double Line" options={doubleLineOptions} />
    </StorybookComponents.Stack>
  );
};
```

#### 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.

```jsx
() => {
  const noPrefixOptions = [
    addressInputItemBuilder({
      id: 1,
      displayLabel: 'Address 1 Country',
      mainLabel: 'Address 1',
      secondaryLabel: 'Country',
      prefix: null,
    }),
    addressInputItemBuilder({
      id: 2,
      displayLabel: 'Address 2 Country',
      mainLabel: 'Address 2',
      secondaryLabel: 'Country',
      prefix: null,
    }),
  ];
  const customPrefixOptions = [
    addressInputItemBuilder({
      id: 1,
      displayLabel: 'Address 1 Country',
      mainLabel: 'Address 1',
      secondaryLabel: 'Country',
      prefix: <Icons.Toolbox />,
    }),
    addressInputItemBuilder({
      id: 2,
      displayLabel: 'Address 2 Country',
      mainLabel: 'Address 2',
      secondaryLabel: 'Country',
      prefix: <Icons.Home />,
    }),
  ];
  return (
    <StorybookComponents.Stack flexDirection="column">
      <AddressInput placeholder="No prefix" options={noPrefixOptions} />
      <AddressInput placeholder="Custom prefix" options={customPrefixOptions} />
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Custom options list

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

```jsx
() => {
  const [value, setValue] = React.useState('');
  const options = [
    listItemActionBuilder({
      id: 0,
      prefixIcon: <Icons.Send />,
      title: 'Use current location',
      as: 'a',
      href: 'https://www.wix.com',
      target: '_blank',
    }),
    listItemSectionBuilder({
      id: 'saved-addresses',
      title: 'Saved Addresses',
      type: 'subheader',
    }),
    addressInputItemBuilder({
      id: 1,
      displayLabel: 'Work 2818 Saint Patrick Pl, Helena, AL, 35080',
      mainLabel: 'Work',
      secondaryLabel: '2818 Saint Patrick Pl, Helena, AL, 35080',
      prefix: <Icons.Toolbox />,
      suffix: '2km away',
      optionLayout: 'double-line',
    }),
    addressInputItemBuilder({
      id: 2,
      displayLabel: 'Home 512 4th St NE, Montgomery, MN, 56069',
      mainLabel: 'Home',
      secondaryLabel: '512 4th St NE, Montgomery, MN, 56069',
      prefix: <Icons.Home />,
      suffix: '34km away',
      optionLayout: 'double-line',
    }),
  ];

  const handleSelect = (value) =>
    setValue(
      value.id === 0 ? 'Didžioji gatvė 28, Vilnius Lithuania' : value.label,
    );
  return (
    <AddressInput
      value={value}
      onSelect={handleSelect}
      placeholder="Search places..."
      options={options}
      onClear={() => setValue('')}
      onChange={(e) => setValue(e.target.value)}
    />
  );
};
```

## Code

```jsx
import { AddressInput } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoSelect` | `boolean` | — | Specifies whether input is auto selected on focus. |
| `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. |
| `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`. |
| `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. |
| `onFocus` | `(e?: FocusEvent<HTMLInputElement, Element> \| undefined) => void` | — | Defines a standard input onFocus callback. |
| `onManuallyInput` | `ManualInputFnSignature` | — | 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. |
| `options` | `DropdownLayoutOption[]` | — | Specify an array of options to render. When the option is an {optionProps}, the <AddressInput.Option/> component is rendered on behalf of the user. |
| `placeholder` | `string` | — | Sets a placeholder message to display. |
| `popoverProps` | `PopoverCommonProps` | — | Allows to pass common popover props. |
| `ref` | `null \| 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. |
| `statusMessage` | `ReactNode` | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
| `value` | `string` | — | Sets a value to display (controlled mode). |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { AddressInputUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { AddressInputTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { AddressInputTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { AddressInputTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| 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. |

## 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