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

## Article: Dropdown Component

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

## Article Content:

# Dropdown

_Components/Form_

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

## Overview

```jsx
() => (
  <Box align="center">
    <Box direction="vertical" width="30%">
      <FormField label="Scheduled payments">
        <Dropdown
          placeholder="Select"
          options={[
            { id: 0, value: 'Weekly' },
            { id: 1, value: 'Monthly' },
            { id: 2, value: 'Yearly' },
          ]}
        />
      </FormField>
    </Box>
  </Box>
);
```

Dropdowns let users select a single item from a predefined list of options.

### Do

- Use when users can select a single item from 5 to 10 options.

### Don't

- Don't use to display two mutually exclusive selections. Use `<ToggleSwitch/>` instead.
- Don't use to display two to four options. Use `<RadioGroup/>` instead.
- Don't use to display 11 or more options. Use `<Autocomplete/>` or `<SelectorList/>` instead.

### Feature examples

#### Size

Adjust the component size using the size prop.

- `large` emphasize fields in onboarding flows.
- `medium` is the default size used in most cases.
- `small` should be used in compact layouts.
- `tiny` should be used in very dense layouts. Avoid using this size when possible.

```jsx
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ];
  return (
    <StorybookComponents.Stack flexDirection="column">
      <Dropdown size="large" placeholder="Large" options={options} />
      <Dropdown size="medium" placeholder="Medium" options={options} />
      <Dropdown size="small" placeholder="Small" options={options} />
      <Dropdown size="tiny" placeholder="Tiny" options={options} />
    </StorybookComponents.Stack>
  );
};
```

#### Border

Style the component using the border prop which supports four 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">
      <Dropdown border="standard" placeholder="Standard" options={options} />
      <Dropdown border="round" placeholder="Round" options={options} />
      <Dropdown
        border="bottomLine"
        placeholder="Bottom Line"
        options={options}
      />
      <Dropdown border="none" placeholder="None" options={options} />
    </StorybookComponents.Stack>
  );
};
```

#### Status

Use the `status` prop to control component status.

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

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">
      <Dropdown status="error" placeholder="Error" options={options} />
      <Dropdown status="warning" placeholder="Warning" options={options} />
      <Dropdown status="loading" placeholder="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 dropdown 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.">
          <Dropdown
            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>
        <Dropdown
          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
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ];
  return <Dropdown disabled placeholder="Disabled" options={options} />;
};
```

#### Affix

Add additional information to `prefix` and `suffix` props (e.g. text, icons, buttons) to support the dropdown value.

```jsx
() => {
  const discountSuffixOptions = [
    { id: 0, value: '5' },
    { id: 1, value: '10' },
    { id: 2, value: '15' },
  ];
  const discountAffixOptions = [
    { id: 0, value: '10' },
    { id: 1, value: '20' },
    { id: 2, value: '30' },
  ];
  const languageOptions = [
    { id: 0, value: 'English' },
    { id: 1, value: 'French' },
    { id: 2, value: 'Spanish' },
  ];
  const employeeOptions = [
    { id: 0, value: 'Employee 1' },
    { id: 1, value: 'Employee 2' },
    { id: 2, value: 'Employee 3' },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <Dropdown
        placeholder="Select discount size"
        suffix={<Input.Affix>%</Input.Affix>}
        options={discountSuffixOptions}
      />
      <Dropdown
        placeholder="Select discount size"
        prefix={<Input.Affix>$</Input.Affix>}
        options={discountAffixOptions}
      />
      <Dropdown
        placeholder="Select language"
        prefix={
          <Input.IconAffix>
            <Icons.Languages />
          </Input.IconAffix>
        }
        options={languageOptions}
      />
      <Dropdown
        placeholder="Select employee"
        prefix={
          <Input.Affix>
            <Avatar size="size18" />
          </Input.Affix>
        }
        options={employeeOptions}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Clear button

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

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

  return (
    <Dropdown
      placeholder="Select"
      clearButton
      onClear={() => setSelectedOption(null)}
      onSelect={(option) => setSelectedOption(Number(option.id))}
      selectedId={selectedOption}
      options={options}
    />
  );
};
```

#### Fixed header and footer

Add related actions to `fixedFooter` or `fixedHeader` areas. These headers and footers keep their position on scroll.

```jsx
() => {
  const options = [
    { id: 1, value: 'Option 1' },
    { id: 2, value: 'Option 2' },
    { id: 3, value: 'Option 3' },
    { id: 4, value: 'Option 4' },
    { id: 5, value: 'Option 5' },
    { id: 6, value: 'Option 6' },
    { id: 7, value: 'Option 7' },
    { id: 8, value: 'Option 8' },
    { id: 9, value: 'Option 9' },
  ];
  return (
    <Dropdown
      placeholder="Select"
      fixedHeader={<ListItemAction title="Fixed Header" />}
      fixedFooter={<ListItemAction title="Fixed Footer" />}
      options={options}
    />
  );
};
```

#### List item builders

Use three props to build custom layouts:

- `listItemSectionBuilder` groups items into sections by type.
- `listItemActionBuilder` adds a text button for related list actions.
- `listItemSelectBuilder` builds custom list designs.

```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">
      <Dropdown
        placeholder="List Item Section"
        options={listItemSectionOptions}
      />
      <Dropdown
        placeholder="List Item Action"
        options={listItemActionOptions}
      />
      <Dropdown
        placeholder="List Item Select"
        options={listItemSelectOptions}
      />
    </StorybookComponents.Stack>
  );
};
```

#### List container dimensions

Control the container size for the list of options with these props:

- `maxHeightPixels` specifies the maximum height for longer lists.
- `dropdownWidth` matches content width or specifies pixels. Set width to 'auto' or 'max-content.'
- `minWidthPixels` manually increases dropdown popover width.

By default, the dropdown matches the input field width.

```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 (
    <StorybookComponents.Stack>
      <Dropdown
        placeholder="Look at proportions"
        maxHeightPixels="200px"
        dropdownWidth="auto"
        minWidthPixels="400px"
        options={options}
        popoverProps={{
          placement: 'bottom-start',
        }}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Marked option

Once the dropdown is opened, use the `markedOption` to highlight the option.

```jsx
<Dropdown
  placeholder="Select an option"
  markedOption={1}
  options={[
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
  ]}
/>;
```

#### Native support

Switch to `native` support for mobile usage. Avoid using it for desktop applications.

```jsx
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
    { id: 3, value: 'Option 4' },
  ];
  return <Dropdown options={options} placeholder="Select as native" native />;
};
```

#### Text overflow

Control text overflow in the field with the `textOverflow`. Apply `clip` or `ellipsis`.

Dropdown list options wrap by default. To apply ellipsis, select the items to be displayed with the `listItemSelectBuilder`. This isn't recommended.

```jsx
() => {
  const options = [
    { id: 0, value: 'Option 1' },
    { id: 1, value: 'Option 2' },
    { id: 2, value: 'Option 3' },
    { id: 3, value: 'Option 4' },
  ];
  const longOptions = [
    {
      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 longOptionsWithEllipsis = [
    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 with ellipsis::">
          <Dropdown
            options={options}
            placeholder="This field is showing ellipsis at the end of this line"
            textOverflow="ellipsis"
          />
        </FormField>
        <FormField label="Input value clipped:">
          <Dropdown
            options={options}
            placeholder="This field is clipping content at the end of this line"
            textOverflow="clip"
          />
        </FormField>
      </StorybookComponents.Stack>
      <StorybookComponents.Stack>
        <FormField label="Options wrapped:">
          <Dropdown options={longOptions} placeholder="Select wrapped option" />
        </FormField>
        <FormField label="Options with ellipsis:">
          <Dropdown
            options={longOptionsWithEllipsis}
            placeholder="Select clipped option"
          />
        </FormField>
      </StorybookComponents.Stack>
    </StorybookComponents.Stack>
  );
};
```

### Developer examples

#### Lazy loading

Gradually load items with `infiniteScroll`, `loadMore` and `hasMore` props.

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

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

  return (
    <Dropdown
      placeholder="Select"
      options={data}
      infiniteScroll
      hasMore={true}
      loadMore={fetchMoreData}
    />
  );
};
```

#### Controlled

Component can be used in controlled mode by passing `selectedId` and `onSelect` props.

```jsx
() => {
  const [selectedId, setSelected] = React.useState(0);

  const options = [
    listItemSelectBuilder({
      id: 0,
      prefix: (
        <Box>
          <Icons.Home />
        </Box>
      ),
      title: 'Home address',
      label: 'Home address',
    }),
    listItemSelectBuilder({
      id: 1,
      title: 'Work address',
      label: 'Work address',
      prefix: (
        <Box>
          <Icons.Toolbox />
        </Box>
      ),
    }),
    listItemSelectBuilder({
      id: 2,
      title: 'Mailing address',
      label: 'Mailing address',
      prefix: (
        <Box>
          <Icons.Email />
        </Box>
      ),
    }),
    listItemSelectBuilder({
      id: 3,
      title: 'Shipping address',
      label: 'Shipping address',
      prefix: (
        <Box>
          <Icons.Archive />
        </Box>
      ),
    }),
    listItemSelectBuilder({
      id: 4,
      title: 'Other',
      label: 'Other',
      prefix: (
        <Box>
          <Icons.Category />
        </Box>
      ),
    }),
  ];

  return (
    <Dropdown
      placeholder="Select"
      selectedId={selectedId}
      valueParser={(option) => option.label}
      onSelect={(e) => setSelected(Number(e.id))}
      options={options}
    />
  );
};
```

### Common use case examples

#### Settings panel

Use dropdown to let users select a single item from a predefined list of options in a settings panel.

```jsx
() => {
  const [selectedOption, setSelectedOption] = React.useState(0);
  const [value, setValue] = React.useState(2);

  const options = [
    { id: 0, value: 'Image' },
    { id: 1, value: 'Video' },
    { id: 2, value: 'Image and video' },
    { id: 3, value: 'Document' },
    { id: 4, value: 'Audio' },
  ];
  return (
    <SidePanel maxHeight="576px" width="288px" skin="floating">
      <SidePanel.Header title="Upload Settings" />
      <SidePanel.Content noPadding>
        <SidePanel.Field>
          <FormField label="Supported file type">
            <Dropdown
              placeholder="Select"
              size="small"
              options={options}
              onSelect={(option) => setSelectedOption(Number(option.id))}
              selectedId={selectedOption}
            />
          </FormField>
        </SidePanel.Field>
        <SidePanel.Field>
          <FieldSet
            gap="small"
            legend="Max number of files"
            columns="auto 60px"
          >
            <Slider
              onChange={(newValue) => setValue(Number(newValue))}
              min={0}
              max={10}
              value={value}
              displayMarks={false}
            />
            <Input
              size="small"
              value={value}
              onChange={(e) => setValue(Number(e.target.value))}
            />
          </FieldSet>
        </SidePanel.Field>
        <SidePanel.Field>
          <FormField label="This field is">
            <Checkbox size="small" checked>
              Required
            </Checkbox>
          </FormField>
        </SidePanel.Field>
        <SidePanel.Section title="Display settings">
          <SidePanel.Field>
            <FormField label="Field title">
              <Input size="small" placeholder="Enter field title" />
            </FormField>
          </SidePanel.Field>
          <SidePanel.Field>
            <FormField label="Button text">
              <Input size="small" value="Choose file" />
            </FormField>
          </SidePanel.Field>
        </SidePanel.Section>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

#### Prefix icon

Use `listItemSelectBuilder` to create custom layouts for options in the dropdown. For example, use avatars, icons or images as prefix icons.

```jsx
() => {
  const options = [
    listItemSelectBuilder({
      id: 0,
      prefix: (
        <Box>
          <Icons.Home />
        </Box>
      ),
      title: 'Home address',
      label: 'Home address',
    }),
    listItemSelectBuilder({
      id: 1,
      title: 'Work address',
      label: 'Work address',
      prefix: (
        <Box>
          <Icons.Toolbox />
        </Box>
      ),
    }),
    listItemSelectBuilder({
      id: 2,
      title: 'Mailing address',
      label: 'Mailing address',
      prefix: (
        <Box>
          <Icons.Email />
        </Box>
      ),
    }),
    listItemSelectBuilder({
      id: 3,
      title: 'Shipping address',
      label: 'Shipping address',
      prefix: (
        <Box>
          <Icons.Archive />
        </Box>
      ),
    }),
    listItemSelectBuilder({
      id: 4,
      title: 'Other',
      label: 'Other',
      prefix: (
        <Box>
          <Icons.Category />
        </Box>
      ),
    }),
  ];

  return (
    <FormField label="Address type">
      <Dropdown
        placeholder="Select"
        valueParser={(option) => option.label}
        options={options}
      />
    </FormField>
  );
};
```

#### Grouping

Use `listItemSectionBuilder` within the drop down to group options into categories.

```jsx
<Layout>
  <Cell span={12}>
    <FormField label="Product">
      <Dropdown
        placeholder="Select"
        options={[
          listItemSectionBuilder({
            id: 'most-popular',
            title: 'Most popular',
          }),
          { id: 1, value: 'Wix Stores' },
          { id: 2, value: 'Wix Bookings' },
          { id: 3, value: 'Wix Blog' },
          listItemSectionBuilder({
            id: 'other',
            title: 'Other',
          }),
          { id: 4, value: 'Wix Events' },
          { id: 5, value: 'Wix Forum' },
          { id: 6, value: 'Wix Restaurants' },
        ]}
      />
    </FormField>
  </Cell>
  <Cell span={12}>
    <FormField label="Role">
      <Dropdown
        placeholder="Select"
        options={[
          listItemSectionBuilder({
            id: 'general',
            title: 'General',
            type: 'subheader',
            suffix: 'Edit',
          }),
          { id: 0, value: 'Website manager' },
          { id: 1, value: 'Website designer' },
          { id: 2, value: 'Back office manager' },
          listItemSectionBuilder({
            id: 'content-manager-roles',
            title: 'Content manager roles',
            type: 'subheader',
            suffix: 'Edit',
          }),
          { id: 3, value: 'Content collection manager' },
          listItemSectionBuilder({
            id: 'blog-roles',
            title: 'Blog roles',
            type: 'subheader',
            suffix: 'Edit',
          }),
          { id: 4, value: 'Blog editor' },
          { id: 5, value: 'Blog writer' },
          { id: 6, value: 'Guest writer' },
          listItemSectionBuilder({
            id: 'booking-roles',
            title: 'Booking roles',
            type: 'subheader',
            suffix: 'Edit',
          }),
          { id: 7, value: 'Bookings admin' },
          { id: 8, value: 'Bookings staff member' },
        ]}
      />
    </FormField>
  </Cell>
</Layout>;
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowTextSelection` | `boolean` | `true` | Controls whether a user can select a text of a selected value. |
| `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. |
| `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. |
| `initialSelectedId` | `string \| number` | — | An initial selected option id. (Implies Uncontrolled mode) |
| `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. |
| `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. |
| `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. |
| `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` | — | Specifies selected option by its id. |
| `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 { DropdownUniDriver } from '@wix/design-system/dist/testkit/unidriver';

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

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

// Testing Library
import { DropdownTestkit } 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.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.317.0** (2026-08-26) — maintenance release, no component-specific changes
- **1.312.0** (2026-08-14) — 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.287.0** (2026-06-10) — fix: dropdownWidth and popoverProps.width ([#16357](invalid-url)) — has visual 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.226.0** (2025-11-10) — feat: displays Drawer in mobile ([#15478](invalid-url)) — has visual changes
- **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.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.211.0** (2025-08-07) — fix: listItemSelectBuilder ability to override size ([#15158](invalid-url))
- **1.210.0** (2025-08-04) — breaking: listItemBuilders respect dropdown size ([#15144](invalid-url))
- **1.205.0** (2025-07-15) — breaking: now items are affected by the Dropdown size ([#15054](invalid-url))
- **1.204.1** (2025-07-09) — fix: adjust selection styling for non-selectable text ([#15067](invalid-url))
- **1.204.0** (2025-07-03) — fix: selectOptionById now closes the popover after selection in visual tests ([#14997](invalid-url))
- **1.203.0** (2025-07-01) — fix: disabled mode ([#15028](invalid-url))
- **1.201.0** (2025-06-23) — feat: allowTextSelection prop added ([#14976](invalid-url))
- **1.199.0** (2025-06-13) — feat: add overlay for Popover content ([#14940](invalid-url))
- **1.191.0** (2025-05-22) — maintenance release, no component-specific changes
- **1.190.0** (2025-05-22) — maintenance release, no component-specific changes
- **1.188.1** (2025-05-14) — fix: opens on space or enter key ([#14855](invalid-url))
- **1.188.1** (2025-05-14) — fix: touch up accessibility ([#14839](invalid-url))
- **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.180.0** (2025-04-14) — 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.2** (2024-05-22) — fix: removed HOC prop exposure to eliminate clashing types ([#13762](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.98.0** (2024-03-15) — fix: fix content padding when wrapped in tooltip ([#13443](invalid-url))
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes