> 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: AtlasAddressInput Component

## Article: AtlasAddressInput Component

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

## Article Content:

# AtlasAddressInput

_Components/Form_

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

## Overview

```jsx
<Box align="center">
  <Box direction="vertical" width="30%">
    <AtlasAddressInput placeholder="Search for address..." />
  </Box>
</Box>;
```

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`

### Do

- Use it as a built-in solution for a location search.
- Use it to enter addresses that must be validated before submitting.

### Don't

- Don't use it when a custom address provider is necessary. Use `<AddressInput/>` which provides the UI only.

### Feature examples

#### Authorization

Requests to Atlas must be authorized using an authorization header. Check out this [Wix Doc](https://bo.wix.com/wix-docs/rest/internal-tools/atlas/introduction#internal-tools_atlas_introduction_atlas-v2-api-authorization) about how to retrieve a signed instance in your environment.

Pass an authorization token to AtlasAddressInput using the `token` prop.

```jsx
<AtlasAddressInput placeholder="Search..." token="some_auth_token" />;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AtlasAddressInput placeholder="Large" size="large" />
  <AtlasAddressInput placeholder="Medium" size="medium" />
  <AtlasAddressInput 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 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.

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

#### Status

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AtlasAddressInput placeholder="Error" status="error" />
  <AtlasAddressInput placeholder="Warning" status="warning" />
  <AtlasAddressInput 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 statusMessage="This is an error message." status="error">
      <AtlasAddressInput placeholder="See message below" />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For narrow layouts only:</Text>
    <AtlasAddressInput
      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
<AtlasAddressInput placeholder="Disabled" disabled />;
```

#### Clear button

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

```jsx
() => {
  const [value, setValue] = React.useState(
    '903  Wilmar Farm Road, Rockville, Maryland',
  );
  return (
    <AtlasAddressInput
      placeholder="Search for address..."
      value={value}
      onChange={(e) => setValue(e.target.value)}
      clearButton={true}
      onClear={() => setValue('')}
    />
  );
};
```

#### Options layout

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AtlasAddressInput placeholder="Single Line" optionLayout="single-line" />
  <AtlasAddressInput placeholder="Double Line" optionLayout="double-line" />
</StorybookComponents.Stack>;
```

#### Options affix

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AtlasAddressInput
    optionPrefix={<Icons.Toolbox />}
    placeholder="Option prefix"
  />
  <AtlasAddressInput optionSuffix="5km away" placeholder="Option suffix" />
</StorybookComponents.Stack>;
```

#### No results

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

```jsx
() => (
  <Box gap="20px" direction="vertical">
    <AtlasAddressInput
      placeholder="Search for an address"
      noResultsText="No matching addresses found"
    />
  </Box>
);
```

#### Localization

Translate search results per country by providing language and locale details.

- Specify the language with `language` prop.
- Specify a required address formatting with `locale` prop.

```jsx
<AtlasAddressInput placeholder="Search..." language="en" locale="en-us" />;
```

### Common use case examples

#### Custom address

Define custom address formatting using `onSelect` callback that provides a `getAddress` function to fetch a [Wix Address Object](invalid-url) from Atlas.

This example displays a post code along with the address.

```jsx
() => {
  const [value, setValue] = React.useState('');

  const onChange = (event) => setValue(event.target.value);

  const onClear = () => setValue('');

  const onSelect = (option, getAddress) => {
    getAddress().then((address) => {
      setValue(`${option.label} - ${address.postalCode}`);
    });
  };

  return (
    <AtlasAddressInput
      onChange={onChange}
      onClear={onClear}
      onSelect={onSelect}
      value={value}
      token="some_auth_token"
      placeholder="Type address and select it"
    />
  );
};
```

## Code

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

### Props

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

## Testkit

Import the driver matching your test environment:

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

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

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

// Testing Library
import { AtlasAddressInputTestkit } 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.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.325.0** (2026-09-17) — 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.289.0** (2026-06-17) — maintenance release, no component-specific changes
- **1.288.0** (2026-06-15) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — 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.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.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.104.1** (2024-05-14) — maintenance release, no component-specific changes
- **1.104.0** (2024-05-06) — maintenance release, no component-specific changes
- **1.98.0** (2024-03-15) — 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