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

## Article: AutoComplete Component

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

## Article Content:

# AutoComplete

_Components/Form_

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

## Overview

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

  const options = [
    { id: 0, value: 'Afghanistan' },
    { id: 1, value: 'Albania' },
    { id: 2, value: 'Algeria' },
    { id: 3, value: 'Andorra' },
    { id: 4, value: 'Angola' },
    { id: 5, value: 'Antigua and Barbuda' },
    { id: 6, value: 'Argentina' },
    { id: 7, value: 'Armenia' },
    { id: 8, value: 'Australia' },
    { id: 9, value: 'Austria' },
    { id: 10, value: 'Azerbaijan' },
    { id: 11, value: 'Bahamas' },
    { id: 12, value: 'Bahrain' },
    { id: 13, value: 'Bangladesh' },
    { id: 14, value: 'Barbados' },
    { id: 15, value: 'Belarus' },
    { id: 16, value: 'Belgium' },
    { id: 17, value: 'Belize' },
    { id: 18, value: 'Benin' },
    { id: 19, value: 'Bhutan' },
    { id: 20, value: 'Bolivia' },
    { id: 21, value: 'Bosnia and Herzegovina' },
    { id: 22, value: 'Botswana' },
    { id: 23, value: 'Brazil' },
    { id: 24, value: 'Brunei' },
    { id: 25, value: 'Bulgaria' },
    { id: 26, value: 'Burkina Faso' },
    { id: 27, value: 'Burundi' },
    { id: 28, value: 'Cabo Verde' },
    { id: 29, value: 'Cambodia' },
    { id: 30, value: 'Cameroon' },
    { id: 31, value: 'Canada' },
    { id: 32, value: 'Central African Republic' },
    { id: 33, value: 'Chad' },
    { id: 34, value: 'Chile' },
    { id: 35, value: 'China' },
    { id: 36, value: 'Colombia' },
    { id: 37, value: 'Comoros' },
    { id: 38, value: 'Congo' },
    { id: 39, value: 'Costa Rica' },
    { id: 40, value: 'Croatia' },
    { id: 41, value: 'Cuba' },
    { id: 42, value: 'Cyprus' },
    { id: 43, value: 'Czech Republic' },
    { id: 44, value: 'Denmark' },
    { id: 45, value: 'Djibouti' },
    { id: 46, value: 'Dominica' },
    { id: 47, value: 'Dominican Republic' },
    { id: 48, value: 'Ecuador' },
    { id: 49, value: 'Egypt' },
    { id: 50, value: 'El Salvador' },
    { id: 51, value: 'Equatorial Guinea' },
    { id: 52, value: 'Eritrea' },
    { id: 53, value: 'Estonia' },
    { id: 54, value: 'Eswatini' },
    { id: 55, value: 'Ethiopia' },
    { id: 56, value: 'Fiji' },
    { id: 57, value: 'Finland' },
    { id: 58, value: 'France' },
    { id: 59, value: 'Gabon' },
    { id: 60, value: 'Gambia' },
  ];

  return (
    <Box align="center">
      <StorybookComponents.Stack flexDirection="column" width={'30%'}>
        <FormField label="Country">
          <AutoComplete
            options={options}
            value={value}
            onChange={(event) => setValue(event.target.value)}
            onSelect={(option) => setValue(String(option.value))}
            placeholder={'Select'}
            emptyStateMessage={`Couldn't find: ${value}`}
            predicate={(option) =>
              String(option.value)
                .toLowerCase()
                .indexOf(value.toLowerCase()) !== -1
            }
            popoverProps={{
              appendTo: 'window',
            }}
          />
        </FormField>
      </StorybookComponents.Stack>
    </Box>
  );
};
```

Autocomplete allows users to select a single item from a predefined list of options. Users can type into the input field to filter the list.

### Do

- Use it to select an item from a list with 10 or more options.
- Use it with user-generated data (e.g., a staff member list, custom categories, labels, products, etc.)

### Don't

- Don't use it when there are fewer than 10 options. Use the `<Dropdown/>` component instead.

### Feature examples

#### Size

Adjust the component size using the `size` prop. It supports 3 sizes.

- Give the dropdown more emphasis with the `large` size.
- `medium` is the default size and should be used in most cases.
- In layouts with a lot of dense content use `small`.

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

  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoComplete placeholder="Large" size="large" options={options} />
      <AutoComplete placeholder="Medium" size="medium" options={options} />
      <AutoComplete placeholder="Small" size="small" options={options} />
    </StorybookComponents.Stack>
  );
};
```

#### Border

Style the component using the `border` prop, which supports 4 styles.

- For forms, use `standard`.
- When the component is used to filter, use `round`.
- For titles that can be edited on click, use `bottomLine`.
- In the Content Manager's spreadsheet, use `none`.

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

  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoComplete
        placeholder="Standard"
        border="standard"
        options={options}
      />
      <AutoComplete placeholder="Round" border="round" options={options} />
      <AutoComplete
        placeholder="Bottom line"
        border="bottomLine"
        options={options}
      />
      <AutoComplete placeholder="None" border="none" options={options} />
    </StorybookComponents.Stack>
  );
};
```

#### Status

Control the component's state using the `status` prop. There are 3 states:

- `error` highlights an invalid selection.
- `warning` highlights a value that can't be validated or impacts the user's business.
- `loading` shows that the server is loading the value.

Hide the status suffix and indicate the state with a border color by setting `hideStatusSuffix` to true.

```jsx
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ];
  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoComplete placeholder="Error" status="error" options={options} />
      <AutoComplete placeholder="Warning" status="warning" options={options} />
      <AutoComplete placeholder="Loading" status="loading" options={options} />
    </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. Control tooltip placement with `tooltipPlacement` prop.

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

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

  return (
    <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.">
          <AutoComplete
            placeholder="See message below"
            tooltipPlacement="top-end"
            options={options}
          />
        </FormField>
      </StorybookComponents.Stack>
      <StorybookComponents.Stack flexDirection="column" gap="12px">
        <Text secondary>For narrow layouts only:</Text>
        <AutoComplete
          placeholder="Hover on status icon"
          status="error"
          statusMessage="This is an error message."
          tooltipPlacement="top-end"
          options={options}
        />
      </StorybookComponents.Stack>
    </StorybookComponents.Stack>
  );
};
```

#### Disabled

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

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

#### Affix

Explain field value with additional information added to `prefix` and `suffix`. Props can contain text, icons and even buttons.

```jsx
() => {
  const languageOptions = [
    { id: 0, value: 'English' },
    { id: 1, value: 'French' },
    { id: 2, value: 'Spanish' },
  ];

  const nameOptions = [
    { id: 0, value: 'Jason Sudeikis' },
    { id: 1, value: 'John Krasinski' },
    { id: 2, value: 'Emma Stone' },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <AutoComplete
        placeholder="Select language"
        prefix={
          <Input.IconAffix>
            <Icons.Languages />
          </Input.IconAffix>
        }
        options={languageOptions}
      />
      <AutoComplete
        placeholder="Assign a person"
        defaultValue="Emma Stone"
        prefix={
          <Input.Affix>
            <Avatar size="size18"></Avatar>
          </Input.Affix>
        }
        suffix={<Input.Affix>12 April 2015</Input.Affix>}
        options={nameOptions}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Clear button

Enable a button that clears the selected value with the `clearButton` prop. Show it when the field value is optional or often has to be cleared.

```jsx
() => {
  const options = [
    { id: 0, value: 'Click clear button to remove selection' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ];

  const [value, setValue] = React.useState(options[0].value);

  return (
    <AutoComplete
      placeholder="Select"
      clearButton
      options={options}
      value={value}
      onClear={() => setValue('')}
    />
  );
};
```

#### Fixed header and footer

Add a list of related actions to a fixed footer or header area. These areas keep their positions on scroll.

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

  return (
    <AutoComplete
      placeholder="Click to see fixed areas"
      fixedHeader={<ListItemAction title="Fixed Header" />}
      fixedFooter={<ListItemAction title="Fixed Footer" />}
      options={options}
    />
  );
};
```

#### List item builders

There are a few props for building custom layouts:

- Group list items into sections with titles using `listItemSectionBuilder`.
- Add text buttons for related list actions with `listItemActionBuilder`.
- Build custom options list designs with `listItemSelectBuilder`.

```jsx
() => {
  const sectionOptions = [
    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 actionOptions = [
    listItemActionBuilder({
      id: 0,
      title: 'Action',
    }),
    { id: 1, value: 'Option 1' },
    { id: 2, value: 'Option 2' },
    { id: 3, value: 'Option 3' },
  ];

  const selectOptions = [
    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">
      <AutoComplete placeholder="List item section" options={sectionOptions} />
      <AutoComplete placeholder="List item action" options={actionOptions} />
      <AutoComplete placeholder="List item select" options={selectOptions} />
    </StorybookComponents.Stack>
  );
};
```

#### List container dimensions

There are a few ways to control the container size:

- Specify the max height for longer lists with `maxHeightPixels` prop.
- Set the width to 'auto' or 'max-content' to match the content width or specify it in pixels with `dropdownWidth` prop.
- Increase the dropdown popover width manually using `minWidthPixels` prop.

```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: 6, value: 'Option 7' },
    { id: 7, value: 'Option 8' },
  ];

  return (
    <AutoComplete
      placeholder="Look at proportions"
      maxHeightPixels="200px"
      dropdownWidth="auto"
      minWidthPixels="400px"
      options={options}
      popoverProps={{
        placement: 'bottom-start',
      }}
    />
  );
};
```

#### Marked option

Control what to highlight with a hover state when autocomplete dropdown is opened with the `markedOption` prop.

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

  return (
    <AutoComplete
      placeholder="Select an option"
      markedOption={1}
      options={options}
    />
  );
};
```

#### Infinite scroll

Load items gradually with `infiniteScroll`, `loadMore` and `hasMore` props.

```jsx
() => {
  const [options, setOptions] = React.useState([]);

  const fetchMoreData = () =>
    Promise.resolve(
      fetch(`/api/dropdown?limit=${5}&offset=${options.length}`),
    ).then((results) => setOptions([...options, ...results]));

  React.useEffect(() => {
    fetchMoreData();
  }, []);

  return (
    <AutoComplete
      infiniteScroll
      hasMore
      loadMore={fetchMoreData}
      options={options}
      placeholder={'Start typing'}
    />
  );
};
```

#### Text overflow

Control text overflow in the input field itself with`textOverflow`. This allows you to clip the content or add ellipsis.

For the dropdown items, the text wraps by default. To add ellipsis, use the `listItemSelectBuilder` prop.

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

  const optionsLongValue = [
    {
      id: 0,
      value: 'This is a long value that make dropdown layout grow',
    },
    {
      id: 1,
      value: 'This is a long value that make dropdown layout grow',
    },
    {
      id: 2,
      value: 'This is a long value that make dropdown layout grow',
    },
  ];

  const optionsListBuilder = [
    listItemSelectBuilder({
      id: 0,
      title: 'This is a long value that make dropdown layout grow',
      ellipsis: true,
    }),
    listItemSelectBuilder({
      id: 0,
      title: 'This is a long value that make dropdown layout grow',
      ellipsis: true,
    }),
    listItemSelectBuilder({
      id: 0,
      title: 'This is a long value that make dropdown layout grow',
      ellipsis: true,
    }),
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <StorybookComponents.Stack>
        <FormField label="Input value - ellipsis">
          <AutoComplete
            options={options}
            placeholder="This field is showing ellipsis at the end of this line"
            textOverflow="ellipsis"
          />
        </FormField>
        <FormField label="Input value - clip">
          <AutoComplete
            options={options}
            placeholder="This field is clipping content at the end of this line"
            textOverflow="clip"
          />
        </FormField>
      </StorybookComponents.Stack>
      <StorybookComponents.Stack>
        <FormField label="Options - wrapping">
          <AutoComplete
            options={optionsLongValue}
            placeholder="Select option that wraps"
          />
        </FormField>
        <FormField label="Options - with ellipsis">
          <AutoComplete
            options={optionsListBuilder}
            placeholder="Select option that clips"
          />
        </FormField>
      </StorybookComponents.Stack>
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Custom lists

To create a custom options layout with avatars, icons, images and more, use the `listItemSelectBuilder`.

```jsx
() => {
  const [searchValue, setSearchValue] = React.useState('');
  const [selectedId, setSelectedId] = React.useState(undefined);

  const options = [
    listItemSectionBuilder({
      id: 'general-roles',
      title: 'General roles',
    }),
    listItemSelectBuilder({
      id: 0,
      title: 'Website manager',
      label: 'Website manager',
      subtitle:
        'Has access to manage, edit & publish site, but cannot manage billing, delete, duplicate or transfer site.',
    }),
    listItemSelectBuilder({
      id: 1,
      title: 'Website designer',
      label: 'Website designer',
      subtitle:
        'Can edit the site, manage settings and apps but cannot access Inbox, contacts and other sensitive info.',
    }),
    listItemSelectBuilder({
      id: 2,
      title: 'Back office manager',
      label: 'Back office manager',
      subtitle:
        'Can access the Dashboard to manage site settings and apps but cannot edit the site.',
    }),
    listItemSectionBuilder({
      id: 'divider-1',
      type: 'divider',
    }),
    listItemSectionBuilder({
      id: 'content-manager-roles',
      title: 'Content manager roles',
    }),
    listItemSelectBuilder({
      id: 3,
      title: 'Content collection manager',
      label: 'Content collection manager',
      subtitle:
        'Can add and modify content for all collections, but cannot edit other areas of your site.',
    }),
    listItemSectionBuilder({
      id: 'divider-2',
      type: 'divider',
    }),
    listItemSectionBuilder({
      id: 'blog-roles',
      title: 'Blog roles',
    }),
    listItemSelectBuilder({
      id: 4,
      title: 'Blog editor',
      label: 'Blog editor',
      subtitle: 'Can fully manage the blog but not other areas of your site.',
    }),
    listItemSelectBuilder({
      id: 5,
      title: 'Blog writer',
      label: 'Blog writer',
      subtitle:
        'Can write and publish posts. Cannot create or manage categories.',
    }),
    listItemSelectBuilder({
      id: 6,
      title: 'Guest writer',
      label: 'Guest writer',
      subtitle:
        'Can write posts but cannot publish them. Posts must be approved and published by a Blog Editor or site owner.',
    }),
    listItemSectionBuilder({
      id: 'divider-3',
      type: 'divider',
    }),
    listItemSectionBuilder({
      id: 'events-roles',
      title: 'Events roles',
    }),
    listItemSelectBuilder({
      id: 7,
      title: 'Events check-in assistant',
      label: 'Events check-in assistant',
      subtitle:
        'Can see the guest list, check-in guests and scan tickets on the Wix Owner App.',
    }),
  ];

  function includesCaseInsensitive(a = '', b = '') {
    return !b || a.toLowerCase().indexOf(b.toLowerCase()) !== -1;
  }

  return (
    <FormField label="Role">
      <AutoComplete
        placeholder="Select"
        maxHeightPixels="300px"
        options={options}
        selectedId={selectedId}
        value={searchValue}
        onSelect={(option) => {
          setSelectedId(option.id);
          setSearchValue(option.label);
        }}
        onChange={(event) => setSearchValue(event.target.value)}
        predicate={(option) =>
          includesCaseInsensitive(option.label, searchValue.trim())
        }
      />
    </FormField>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaControls` | `string` | — | Associate a control with the regions that it controls. |
| `ariaDescribedby` | `string` | — | Associate a region with its descriptions. Similar to aria-controls but instead associating descriptions to the region and description identifiers are separated with a space. |
| `ariaLabel` | `string` | — | Define a string that labels the current element in case where a text label isn't visible on the screen. |
| `ariaRoledescription` | `string` | — | Sets the `aria-roledescription` attribute of the `<input>` element, giving assistive technologies a readable description of its role. |
| `autocomplete` | `string` | `'off'` | Sets the value of the native `autocomplete` attribute of the input. |
| `autoFocus` | `boolean` | — | Focus the element on mount (standard React input autoFocus) |
| `autoSelect` | `boolean` | — | Automatically selects the entire input text. |
| `backgroundColor` | `string` | — | Sets the background color of the input. Accepts any CSS color value. |
| `border` | `"none" \| "standard" \| "round" \| "bottomLine"` | — | Control the border style of input. |
| `children` | `ReactNode` | — |  |
| `clearButton` | `boolean` | — | Displays clear button (X) on a non-empty input. |
| `clearButtonAriaLabel` | `string` | — | Aria label for the clear button. |
| `clearButtonTooltipContent` | `ReactNode` | — | When provided, hovering displays a tooltip with this content. |
| `clearButtonTooltipProps` | `TooltipCommonProps` | — | Clear button tooltip props. |
| `closeOnSelect` | `boolean` | `true` | Closes DropdownLayout on option selection. |
| `customDropdownContent` | `ReactNode` | — | Accepts any content to render in the dropdown instead of the options list. Ignored when `native` is `true`. |
| `customInput` | `ReactNode \| Function` | — | Render a custom input instead of the default html input tag. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `defaultValue` | `string \| number` | — | Defines the initial value of an input. |
| `disabled` | `boolean` | — | Specifies whether input should be disabled or not. |
| `disableEditing` | `boolean` | — | Restricts input editing. |
| `dropDirectionUp` | `boolean` | — | Specifies whether the list opens upward. Aligns the list container to the bottom and positions the arrow for upward direction. |
| `dropdownOffsetLeft` | `string` | `'0'` | Sets the offset of the dropdown from the left. |
| `dropdownWidth` | `string` | `null` | Sets the width of the dropdown. |
| `emptyStateMessage` | `ReactNode` | — | Defines a message to be displayed instead of options when no options exist or no options pass the predicate filter function. |
| `enterKeyHint` | `"search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"` | — | Sets the label of the virtual keyboard's enter key on touch devices. |
| `fixedFooter` | `ReactNode` | — | A fixed footer to the list. |
| `fixedHeader` | `ReactNode` | — | A fixed header to the list. |
| `focusOnClearClick` | `boolean` | — | Specifies whether to focus the field when clear button is clicked. |
| `focusOnOption` | `string \| number` | — | Marks (not selects) and scrolls view to the option on opening the dropdown by option id. |
| `focusOnSelectedOption` | `boolean` | — | Scroll view to the selected option on opening the dropdown. |
| `hasMore` | `boolean` | — | Whether there are more items to be loaded. |
| `hideStatusSuffix` | `boolean` | — | Specifies whether status suffix should be hidden. |
| `highlight` | `boolean` | — | Mark in bold word parts based on search pattern. |
| `id` | `string` | — | Assigns a unique identifier for the root element. |
| `inContainer` | `boolean` | — | Whether the `<DropdownLayout/>` is in a container component. If `true`, some styles such as shadows, positioning and padding are added to the component contentContainer. |
| `infiniteScroll` | `boolean` | — | Set this prop for lazy loading of the dropdown layout items. |
| `inputElement` | `ReactElement` | — | Use a customized input component instead of the default |
| `inputmode` | `string` | — | Sets the value of the native `inputmode` attribute, which tells mobile browsers which on-screen keyboard to show, for example `numeric` or `email`. |
| `inputRef` | `null \| (instance: HTMLInputElement \| null) => void \| RefObject<HTMLInputElement>` | — | Ref to the underlying `<input>` DOM element. Accepts callback and object refs. Use for input masking libraries such as `use-mask-input`. Memoize callback refs to avoid reattaching on every render. |
| `itemHeight` | `"big" \| "small"` | `'small'` | Controls the minimum height of options that aren't builder options. |
| `listboxId` | `string` | — | Defines the id for the listbox. |
| `listType` | `"select" \| "action"` | — | Defines type of behavior applied in list. |
| `loadMore` | `(page: number) => void` | — | A callback called when more items are requested to be rendered. |
| `markedOption` | `string \| number \| false \| true` | — | Sets the default hover behavior when: 1. `false` means no default 2. `true` means to hover the first selectable option 3. Any number/string represents the id of option to hover |
| `max` | `number` | — | Sets a maximum value of an input. Similar to html5 max attribute. |
| `maxHeightPixels` | `string \| number` | — | Set the max height of the dropdownLayout in pixels. |
| `maxLength` | `number` | — | Sets the maximum number of characters that can be inserted to a field. |
| `menuArrow` | `boolean` | — | Specifies whether input should have a dropdown menu arrow on the right side. |
| `min` | `number` | — | Sets a minimum value of an input. Similar to HTML5 min attribute. |
| `minWidthPixels` | `string \| number` | — | Set the min width of the dropdownLayout in pixels. |
| `name` | `string` | — | Reference element data when a form is submitted. |
| `native` | `boolean` | `false` | Indicates whether to render using the native select element. |
| `noLeftBorderRadius` | `boolean` | — | Specifies whether input shouldn't have rounded corners on its left. |
| `noRightBorderRadius` | `boolean` | — | Specifies whether input shouldn't have rounded corners on its right. |
| `onBlur` | `FocusEventHandler` | — | Defines a standard input onBlur callback. |
| `onChange` | `ChangeEventHandler` | — | Defines a standard input onChange callback. |
| `onClear` | `(event: KeyboardEvent<HTMLButtonElement> \| MouseEvent<HTMLButtonElement, MouseEvent>) => void` | — | Displays clear button (X) on a non-empty input and calls a callback function. |
| `onClickOutside` | `(e: MouseEvent \| TouchEvent) => void` | — | Defines a callback function which is called when the user clicks or touches outside the list while it's visible. |
| `onClose` | `() => void` | — | Callback function called whenever the user press the `Escape` keyboard. |
| `onCompositionChange` | `(isComposing: boolean) => void` | — | Defines a callback function called on compositionstart/compositionend events. |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut) |
| `onDrillIn` | `(option: DropdownLayoutValueOption) => void` | — | Called when the user presses ArrowRight on a hovered option. Use to move focus into an interactive child element (e.g. an actions menu). |
| `onDrillOut` | `() => void` | — | Called when the user navigates back from a drilled-in child element (e.g. via ArrowLeft or Escape). Use to restore focus to the trigger input. |
| `onEmptyState` | `() => void` | — | Defines a callback function which is called when no options exist. |
| `onEnterPressed` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when the user presses -enter-. |
| `onEscapePressed` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when the user presses -escape-. |
| `onFocus` | `FocusEventHandler` | — | Defines a standard input onFocus callback. |
| `onInputClicked` | `MouseEventHandler` | — | Defines a standard input onClick callback. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a standard input onKeyDown callback. |
| `onKeyUp` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a standard input onKeyUp callback. |
| `onManuallyInput` | `ManualInputFnSignature` | — | A callback which is called when the user performs a Submit-Action. Submit-Action triggers are: "Enter", "Tab", [typing any defined delimiters], Paste action. `onManuallyInput(values: Array<string>): void - The array of strings is the result of splitting the input value by the given delimiters |
| `onMouseDown` | `MouseEventHandler` | — | Callback function called whenever the user clicks the dropdown layout. |
| `onMouseEnter` | `MouseEventHandler` | — | Callback function called whenever the user entered with the mouse to the dropdown layout. |
| `onMouseLeave` | `MouseEventHandler` | — | Callback function called whenever the user exited with the mouse from the dropdown layout. |
| `onOptionMarked` | `(option: DropdownLayoutValueOption \| null, optionElementId?: string \| undefined) => void` | — | Callback function called whenever an option becomes focused (hovered/active). Receives the relevant option object from the original props.options array. |
| `onOptionsHide` | `() => void` | — | A callback which is called when options dropdown is hidden. |
| `onOptionsNavigate` | `(option: DropdownLayoutValueOption \| null) => void` | — | Callback function called whenever the user navigates to an option (via keyboard or mouse). Receives the relevant option object from the original props.options array, or null when navigation is cleared. |
| `onOptionsShow` | `() => void` | — | A callback which is called when options dropdown is shown. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut) |
| `onSelect` | `(option: DropdownLayoutValueOption, sameOptionWasPicked: boolean) => void` | — | Defines a callback function which is called when the user selects an option from the list. When `highlight` is `true`, it receives the original option from `options`. |
| `options` | `DropdownLayoutOption[]` | — | Array of objects: - id `<string / number>` *required*: the id of the option, should be unique. - value `<function / string / node>` *required*: can be a string, react element or a builder function. - disabled `<bool>` *default value- false*: whether this option is disabled or not - linkTo `<string>`: when provided, the option is an anchor to the given value - title `<bool>`  *default value- false*  **deprecated**: use `listItemSectionBuilder` to render a title instead. - overrideStyle `<bool>` *default value- false*  **deprecated**: use `overrideOptionStyle` to override option styles instead. - overrideOptionStyle `<bool>` *default value- false* - when set to `true`, the option is responsible for its own styles. No styles are applied from the DropdownLayout itself. - label `<string>`: the string displayed within an input when the option is selected. This is used when using `<DropdownLayout/>` with an `<Input/>`. |
| `overflow` | `"visible" \| "hidden" \| "auto" \| "scroll"` | — | Set overflow of container. |
| `pattern` | `string` | — | Sets a pattern that typed value must match to be valid (regex) |
| `placeholder` | `string` | — | Sets a placeholder message to display. |
| `popoverProps` | `PopoverCommonProps` | — | Accepts common popover props that are passed to the options dropdown popover. |
| `predicate` | `(option: DropdownLayoutValueOption, index: number, array: DropdownLayoutValueOption[]) => boolean` | — | Defines a callback predicate for the filtering options function. |
| `prefix` | `ReactNode` | — | Pass a component you want to show as the prefix of the input, e.g., text, icon. |
| `readOnly` | `boolean` | — | Specifies whether input is read only. |
| `ref` | `null \| string \| (instance: AutoCompleteComponent \| null) => void \| RefObject<AutoCompleteComponent>` | — | 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). |
| `required` | `boolean` | — | Specifies whether input is mandatory. |
| `role` | `string` | — | Specifies the role of the input element for accessibility. |
| `rtl` | `boolean` | — | Specifies text direction. If true, the text is displayed from right to left. |
| `scrollbar` | `"fixed" \| "overlay"` | — | Controls which type of scrollbar to render. |
| `scrollToOption` | `string \| number` | — | Scrolls to the specified option when dropdown is opened without marking it. |
| `selectedHighlight` | `boolean` | `true` | Whether the selected option is highlighted when the dropdown reopens. |
| `selectedId` | `string \| number` | — | The id of the selected option in the list. |
| `showDrawerOnMobile` | `boolean` | `true` | Controls whether to show drawer on mobile devices. |
| `showOptionsIfEmptyInput` | `boolean` | `true` | Controls whether to show options if input is empty. |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | `'medium'` | Controls the size of the input and its dropdown options. `tiny` and `small` inputs render `small` options, the rest render `medium` ones. |
| `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. |
| `statusMessageTooltipProps` | `TooltipCommonProps` | — | Status message tooltip props. |
| `step` | `number` | — | Specifies the interval between number values. |
| `suffix` | `ReactNode` | — | Pass a component you want to show as the suffix of the input, e.g., text, icon. |
| `tabIndex` | `number` | — | Indicates that element can be focused and where it participates in sequential keyboard navigation. |
| `textOverflow` | `"ellipsis" \| "clip"` | — | Handles text overflow behavior. It can either `clip` (default) or display `ellipsis`. |
| `tooltipPlacement` | `"right" \| "left" \| "top" \| "bottom" \| "auto" \| "auto-start" \| "auto-end" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-end" \| "bottom-start" \| "left-end" \| "left-start"` | — | Controls placement of a status tooltip. |
| `type` | `string` | — | Specifies the type of `<input/>` element to display. Default is text. |
| `value` | `string \| number` | — | Specifies the current value of the element. |
| `valueParser` | `(option: DropdownLayoutValueOption) => ReactNode \| RenderOptionFn` | — | Function that receives an option, and should return the value to be displayed. |
| `visible` | `boolean` | — | Should show or hide the component. |
| `withArrow` | `boolean` | — | Displays an arrow on the list container while it's visible. |
| `withSelection` | `boolean` | — |  |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `exists` | — |
| `driver` | — |
| `inputDriver` | — |
| `dropdownLayoutDriver` | — |

## 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.323.0** (2026-09-10) — 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.289.0** (2026-06-17) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — 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.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.232.0** (2025-11-28) — fix: stop Escape key propagation to parent elements ([#15559](invalid-url))
- **1.220.2** (2025-10-06) — maintenance release, no component-specific changes
- **1.213.0** (2025-08-19) — maintenance release, no component-specific changes
- **1.187.0** (2025-05-07) — 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.115.0** (2024-07-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