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

## Article: AutoCompleteWithLabel Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/auto-complete-with-label-component.md

## Article Content:

# AutoCompleteWithLabel

_Components/Form/AutoCompleteWithLabel_

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

## Overview

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

  return (
    <StorybookComponents.Stack flexDirection="column" width="50%">
      <AutoCompleteWithLabel
        options={[
          { id: 0, value: 'Carmel Lloyd' },
          { id: 1, value: 'Gracie-May Marsden' },
          { id: 2, value: 'Keisha Decker' },
          { id: 3, value: 'Ruairidh Fitzgerald' },
          { id: 4, value: 'Sheldon Chavez' },
        ]}
        value={value}
        maxHeightPixels="300px"
        label="Site Owner"
        onChange={(e) => setValue(e.target.value)}
        onSelect={(option) => setValue(String(option.value))}
      />
    </StorybookComponents.Stack>
  );
};
```

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.

### Do

- Use it in Wix Premium checkout form.

### Don't

- Don't use it in Wix Business Manager applications, use `<Autocomplete/>` instead.

### Feature examples

#### Status

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

```jsx
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoCompleteWithLabel label="Error" status="error" options={options} />
      <AutoCompleteWithLabel
        label="Warning"
        status="warning"
        options={options}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Status Message

Explain the status with \`statusMessage\` prop.\
\
It only works when \`status\` is set to \`error\`.

```jsx
<AutoCompleteWithLabel
  label="Error"
  options={[
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ]}
  status="error"
  statusMessage="Message that explains the status"
/>;
```

#### Disabled

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

```jsx
<AutoCompleteWithLabel label="Disabled" disabled />;
```

#### Suffix

Explain the field value with additional information added to the \`suffix\` area. This prop accepts text, icons and even buttons.

```jsx
<AutoCompleteWithLabel
  suffix={[<Text>Suffix</Text>]}
  label="my autocomplete"
  options={[
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ]}
/>;
```

#### List item builders

Build custom layouts with:\
 - \`listItemSectionBuilder\` - use it to group list items into sections by type. See [ListItemSection](https://www.wix-pages.com/wix-design-system-employees/?path=/story/components-api-components--listitemsection) for more details.\
 - \`listItemActionBuilder\` - use it to add text buttons for related list actions, e.g., 'Manage categories'. See [ListItemAction](https://www.wix-pages.com/wix-design-system-employees/?path=/story/components-api-components--listitemaction) for more details.\
 - \`listItemSelectBuilder\` - use it to build custom list designs. See [ListItemSelect](https://www.wix-pages.com/wix-design-system-employees/?path=/story/components-api-components--listitemselect) for more details.

```jsx
() => {
  const listItemSectionOptions = [
    listItemSectionBuilder({
      id: 0,
      type: 'title',
      title: 'Group Title',
    }),
    { id: 1, value: 'Option 1' },
    { id: 2, value: 'Option 2' },
    { id: 3, value: 'Option 3' },
    listItemSectionBuilder({
      id: 3,
      type: 'divider',
    }),
    { id: 4, value: 'Option 4' },
  ];

  const listItemActionOptions = [
    listItemActionBuilder({
      id: 0,
      title: 'Action',
    }),
    { id: 1, value: 'Option 1' },
    { id: 2, value: 'Option 2' },
    { id: 3, value: 'Option 3' },
  ];

  const listItemSelectOptions = [
    listItemSelectBuilder({
      id: 0,
      prefix: <Avatar size="size30" />,
      title: 'Title',
      subtitle: 'Subtitle',
      suffix: 'Suffix',
    }),
    listItemSelectBuilder({
      id: 1,
      prefix: <Avatar size="size30" />,
      title: 'Title',
      subtitle: 'Subtitle',
      suffix: 'Suffix',
    }),
    listItemSelectBuilder({
      id: 2,
      prefix: <Avatar size="size30" />,
      title: 'Title',
      subtitle: 'Subtitle',
      suffix: 'Suffix',
    }),
  ];
  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoCompleteWithLabel
        label="List Item Section"
        options={listItemSectionOptions}
      />
      <AutoCompleteWithLabel
        label="List Item Action"
        options={listItemActionOptions}
      />
      <AutoCompleteWithLabel
        label="List Item Select"
        options={listItemSelectOptions}
      />
    </StorybookComponents.Stack>
  );
};
```

#### List container height

Control container size with \`maxHeightPixels\` prop. Use it to restrict the height of longer lists of options.

```jsx
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
    { id: 3, value: 'Option 4' },
    { id: 4, value: 'Option 5' },
    { id: 5, value: 'Option 6' },
    { id: 0, value: 'Option 7' },
    { id: 1, value: 'Option 8' },
    { id: 2, value: 'Option 9' },
    { id: 3, value: 'Option 10' },
    { id: 4, value: 'Option 11' },
    { id: 5, value: 'Option 12' },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoCompleteWithLabel
        label="Max Height 180px"
        maxHeightPixels="180px"
        options={options}
      />
      <AutoCompleteWithLabel
        label="Max Height 400px"
        maxHeightPixels="400px"
        options={options}
      />
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Checkout Form

The autocomplete selection only be used in a Premium Checkout form.

```jsx
() => {
  const countries = [
    { id: 0, value: 'Australia' },
    { id: 1, value: 'Austria' },
    { id: 2, value: 'Guinea-Bissau' },
    { id: 3, value: 'Mauritania' },
    { id: 4, value: 'Mauritius' },
    { id: 5, value: 'Nauru' },
  ];

  return (
    <Layout>
      <Cell>
        <InputWithLabel
          label="Address"
          suffix={[
            <InfoIcon content="Your address must match your credit card's billing address." />,
          ]}
        />
      </Cell>
      <Cell span={6}>
        <InputWithLabel label="City" />
      </Cell>
      <Cell span={6}>
        <InputWithLabel label="Postal Code" />
      </Cell>
      <Cell span={6}>
        <AutoCompleteWithLabel label="Country" options={countries} />
      </Cell>
      <Cell span={6}>
        <InputWithLabel label="Phone" />
      </Cell>
    </Layout>
  );
};
```

## Code

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

### Props

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

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

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

## 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.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.322.0** (2026-09-09) — 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.259.1** (2026-03-02) — maintenance release, no component-specific changes
- **1.248.0** (2026-01-23) — fix: guard against undefined option in onSelect ([#15833](invalid-url))
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.124.0** (2024-09-06) — 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