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

## Article: MultiSelect Component

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

## Article Content:

# MultiSelect

_Components/Form_

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

## Overview

```jsx
() => {
  const [addedTags, setAddedTags] = React.useState([]);

  const options = [
    { id: 1, value: 'Pottery class' },
    { id: 2, value: 'Circle workout' },
  ];

  const baseDropdownItems = [
    ...options,
    listItemSectionBuilder({
      id: 3,
      type: 'divider',
    }),
    listItemActionBuilder({
      id: 4,
      title: 'All services',
    }),
  ];

  const [dropdownItems, setDropdownItems] = React.useState(baseDropdownItems);

  const addTag = (option) => {
    const tags =
      option.id === 4
        ? options.map((option) => ({ id: option.id, label: option.value }))
        : [...addedTags, { id: option.id, label: option.value }];

    tags.length === 2
      ? setDropdownItems(
          baseDropdownItems.filter((item) => Number(item.id) < 3),
        )
      : setDropdownItems(baseDropdownItems);

    setAddedTags(tags);
  };

  const removeTag = (tagId) => {
    setAddedTags(addedTags.filter((tag) => tag.id !== tagId));
    setDropdownItems(baseDropdownItems);
  };

  return (
    <Box align="center">
      <Box direction="vertical" width="30%">
        <FormField label="Included services">
          <MultiSelect
            tags={addedTags}
            options={dropdownItems}
            onSelect={(option) => addTag(option)}
            onRemoveTag={(tagId) => removeTag(tagId)}
            customSuffix={<TextButton>+ Add Service</TextButton>}
          />
        </FormField>
      </Box>
    </Box>
  );
};
```

Multiselect allows users to enter and display multiple keyword tags.

### Do

- Use it when the site owner needs to enter multiple keywords like names, emails, countries, etc.
- Use it as a tag input.

### Don't

- Don't use it to insert tags in combination with free text. Use `<VariableInput/>` instead.

### Feature examples

#### Size

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

- `large` is best for onboarding flows, where input needs emphasis.
- `medium` (default) – use for most cases.
- `small` is appropriate for dense and narrow layouts.

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

  const renderMultiSelect = ({ size, tagSize }) => {
    const [tags, setTags] = React.useState([
      {
        size: tagSize,
        id: '1',
        label: 'tag 1',
      },
      {
        size: tagSize,
        id: '2',
        label: 'tag 2',
      },
    ]);

    const handleOnSelect = (tag) =>
      setTags([...tags, { id: tag.id, label: tag.value, size: tagSize }]);

    const handleOnRemoveTag = (tagId) =>
      setTags(tags.filter((currTag) => currTag.id !== tagId));

    return (
      <MultiSelect
        size={size}
        options={options}
        tags={tags}
        onSelect={handleOnSelect}
        onRemoveTag={handleOnRemoveTag}
      />
    );
  };

  return (
    <StorybookComponents.Stack flexDirection="column">
      <FormField label="Large">
        {renderMultiSelect({ size: 'large', tagSize: 'medium' })}
      </FormField>
      <FormField label="Medium">
        {renderMultiSelect({ size: 'medium', tagSize: 'small' })}
      </FormField>
      <FormField label="Small">
        {renderMultiSelect({ size: 'small', tagSize: 'tiny' })}
      </FormField>
    </StorybookComponents.Stack>
  );
};
```

#### Border

Style the component using the `border` prop. It supports 4 styles:

- For forms and most common cases, use `default`.
- When component is used to filter data, use `round`.
- Use `bottomLine` to create an editable, underlined title field.
- When a component provides its own hover and focus styles, such as a table or spreadsheet cells, use `none`.

```jsx
() => {
  const options = [
    { 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' },
  ];

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

#### Status

Control the component status using a `status` prop. It supports 3 states:

- `error` demonstrates that a required input is missing something or the entry was invalid.
- `warning` highlights a value that might have a significant impact to a user.
- `loading` shows when a value is being uploaded to the server.

```jsx
() => {
  const options = [
    { 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' },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <MultiSelect status="error" placeholder="Error" options={options} />
      <MultiSelect status="warning" placeholder="Warning" options={options} />
      <MultiSelect 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 component 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 = [
    { 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' },
  ];

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

#### Read-only and disabled

Multi select can also be made read-only or disabled entirely.

- `readOnly` disables adding or editing, but allows the user to copy the current value. Use it to display URLs, code, etc.
- `disabled` removes all interactions and creates a disabled component state. Use it to highlight functions that are unavailable.

```jsx
() => {
  const options = [
    { 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' },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <MultiSelect value="Read Only" readOnly />
      <MultiSelect
        placeholder="Disabled"
        mode="select"
        options={options}
        disabled
      />
    </StorybookComponents.Stack>
  );
};
```

#### Action

Encourage user engagement by displaying the call to action. To add a [`<TextButton/>`](https://wix-pages.com/design-system-documentation/#/component/textbutton), use the `customSuffix` property.

```jsx
() => {
  const [tags, setTags] = React.useState([]);

  const handleOnSelect = (tag) =>
    setTags([...tags, { id: tag.id, label: tag.value }]);

  const handleOnRemoveTag = (tagId) =>
    setTags(tags.filter((currTag) => currTag.id !== tagId));

  return (
    <MultiSelect
      tags={tags}
      options={[
        { id: '1', value: 'tag 1' },
        { id: '2', value: 'tag 2' },
        { id: '3', value: 'tag 3' },
      ]}
      customSuffix={
        <Box>
          <TextButton prefixIcon={<Icons.Add />}>Add Tag</TextButton>
        </Box>
      }
      onSelect={handleOnSelect}
      onRemoveTag={handleOnRemoveTag}
    />
  );
};
```

#### Select mode

Allow users to select only options that are listed with `mode` prop.

```jsx
() => {
  const [tags, setTags] = React.useState([]);

  const handleOnSelect = (tag) =>
    setTags([...tags, { id: tag.id, label: tag.value }]);

  const handleOnRemoveTag = (tagId) =>
    setTags(tags.filter((currTag) => currTag.id !== tagId));

  return (
    <MultiSelect
      tags={tags}
      options={[
        { id: '1', value: 'tag 1' },
        { id: '2', value: 'tag 2' },
        { id: '3', value: 'tag 3' },
      ]}
      mode="select"
      placeholder="Select tags from a list"
      onSelect={handleOnSelect}
      onRemoveTag={handleOnRemoveTag}
    />
  );
};
```

#### Manual input

Allow users to enter their own tags using the keyboard with `onManuallyInput` property.

```jsx
() => {
  const [tags, setTags] = React.useState([]);

  const handleManualInput = (tag) =>
    setTags([...tags, { id: Math.random(), label: tag[0] }]);

  const handleOnRemoveTag = (tagId) =>
    setTags(tags.filter((currTag) => currTag.id !== tagId));

  return (
    <MultiSelect
      tags={tags}
      placeholder="Type custom tags and separate them with the Enter key"
      onManuallyInput={handleManualInput}
      onRemoveTag={handleOnRemoveTag}
    />
  );
};
```

#### Predicate

Build autocomplete features using the `predicate` property.

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

  const options = [
    { value: 'Alabama', id: 'AL' },
    { value: 'California', id: 'CA' },
    { value: 'North Carolina', id: 'NC' },
    { value: 'Colorado', id: 'CO' },
    { value: 'Connecticut', id: 'CT' },
  ];

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

  const predicate = (option) =>
    option.value && option.value.toLowerCase().includes(value.toLowerCase());

  const handleOnSelect = (tag) =>
    setTags([...tags, { id: tag.id, label: tag.value }]);

  const handleOnRemoveTag = (tagId) =>
    setTags(tags.filter((currTag) => currTag.id !== tagId));

  return (
    <MultiSelect
      predicate={predicate}
      tags={tags}
      value={value}
      options={options}
      onChange={handleOnChange}
      placeholder="Start typing a state to find a match"
      onSelect={handleOnSelect}
      onRemoveTag={handleOnRemoveTag}
    />
  );
};
```

#### Reorder

Use the `onReorder` property to allow users to change the order in which keywords are displayed.

```jsx
() => {
  const [tags, setTags] = React.useState([
    { id: '1', label: 'One' },
    { id: '2', label: 'Two' },
    { id: '3', label: 'Three' },
  ]);

  const options = [
    { id: '1', value: 'One' },
    { id: '2', value: 'Two' },
    { id: '3', value: 'Three' },
  ];

  const handleOnSelect = (tag) =>
    setTags([...tags, { id: tag.id, label: tag.value }]);

  const handleOnRemoveTag = (tagId) =>
    setTags(tags.filter((currTag) => currTag.id !== tagId));

  return (
    <MultiSelect
      tags={tags}
      options={options}
      onReorder={({ addedIndex, removedIndex }) => {
        const nextTags = tags.slice();
        nextTags.splice(addedIndex, 0, ...nextTags.splice(removedIndex, 1));
        setTags(nextTags);
      }}
      onSelect={handleOnSelect}
      onRemoveTag={handleOnRemoveTag}
    />
  );
};
```

### Common use case examples

#### Enter contact emails

Multiselect input can be useful for entering contacts or emails.

If combined with advanced list item props, multiselect can provide explicit information, therefore, making multiple keyboard entries easier.

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

  const contacts = [
    { name: 'River Watts', email: 'riverw@wix.com', id: 1 },
    { name: 'Jesse Neimus', email: 'jessen@wix.com', id: 2 },
    { name: 'Morgan James', email: 'morganj@wix.com', id: 3 },
    { name: 'Reese Whiteman', email: 'reesew@wix.com', id: 4 },
  ];

  const options = contacts.map((contact) => ({
    ...contact,
    ...listItemSelectBuilder({
      prefix: (
        <Avatar
          size="size30"
          imgProps={{ src: `AvatarExample${contact.id}.jpg` }}
        />
      ),
      id: contact.id,
      title: contact.name,
      subtitle: contact.email,
    }),
  }));

  const handleOnSelect = (option) => {
    const { name, email, id } = option;
    setTags([...tags, { id, label: name ? `${email} (${name})` : email }]);
  };

  const handleOnRemoveTag = (tagId) =>
    setTags(tags.filter((currTag) => currTag.id !== tagId));

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

  const predicate = (option) =>
    (option.name + option.email).toLowerCase().includes(value.toLowerCase());

  return (
    <MultiSelect
      value={value}
      options={options}
      tags={tags}
      onChange={handleOnChange}
      onSelect={handleOnSelect}
      onRemoveTag={handleOnRemoveTag}
      placeholder="Start typing a name to find a match"
      predicate={predicate}
    />
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `acceptOnBlur` | `boolean` | — | When set to true, the input is submitted as a new tag on blur. |
| `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` | — | Sets the text of the tag. |
| `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. |
| `clearOnBlur` | `boolean` | `true` | When set to false, the input won't be cleared on blur. |
| `closeOnSelect` | `boolean` | `true` | Closes list once list item is selected. |
| `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. By default, it renders an input that sizes itself to its text. |
| `customPrefix` | `ReactNode` | — | A node to display as input prefix when the dropdown is closed. |
| `customSuffix` | `ReactNode` | — | A node to display as input suffix when the dropdown is closed. |
| `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. |
| `delimiters` | `string[]` | — | Delimiters that trigger a Submit action (call to onTagsAdded). By default it is [,] but also enter and tab keys work. |
| `disabled` | `boolean` | — | When set to true this component is disabled. |
| `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` | — | Adds a fixed footer container at the bottom of options 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. |
| `maxNumRows` | `number` | — | Max number of visible lines. |
| `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. |
| `mode` | `"select"` | — | Passing 'select' renders a readOnly input with menuArrow suffix *. |
| `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` | `(values: string[]) => void` | — | 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) |
| `onRemoveTag` | `(tagId: string) => void` | — | A callback function to be called when a tag should be removed. The expected callback signature is `onRemoveTag(tagId: number \| string) => void.` |
| `onReorder` | `OnReorderFn` | — | When this callback function is set, tags can be reordered. The expected callback signature is `onReorder({addedIndex: number, removedIndex: number}) => void` *. |
| `onSelect` | `(option: DropdownLayoutValueOption) => void` | — | A callback which is called when the user selects an option from the list. `onSelect(option: Option): void` - Option is the original option from the provided options prop. |
| `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) => boolean` | — | 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 should be 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` | — | 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"` | — | The status of the input. |
| `statusMessage` | `ReactNode` | — | Text to be shown in the status icon tooltip. |
| `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. |
| `tags` | `MultiSelectTag[]` | — | Optional list of strings that are selected suggestions. |
| `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

No testkit for this component — it doesn't expose a unidriver testkit.

## Changelog

- **1.344.0** (2026-10-28) — maintenance release, no component-specific changes
- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.331.0** (2026-10-01) — fix: no longer shows an inset shadow around the typing area inside the field, which made it look like an input inside an input in Harmony (odeditor). ([#17313](invalid-url))
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.326.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.312.0** (2026-08-14) — fix: border radius now matches Input across sizes and themes, and the border highlights on hover. ([#16814](invalid-url)) — has visual 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.288.0** (2026-06-15) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.263.0** (2026-03-31) — fix: added scrollable container to not allow tags to overlap ([#15964](invalid-url))
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.258.0** (2026-02-23) — fix: fixed issue with max row num provided ([#15962](invalid-url))
- **1.251.0** (2026-01-28) — fix: prevent Escape key event from propagating ([#15868](invalid-url))
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.232.0** (2025-11-28) — maintenance release, no component-specific changes
- **1.215.0** (2025-08-27) — fix: dropdown not displaying empty state, and scrollbar issue ([#15249](invalid-url))
- **1.215.0** (2025-08-27) — fix: opening dropdown with only fixedFooter provided ([#15247](invalid-url))
- **1.214.2** (2025-08-25) — breaking: tokenization for e3 ([#15221](invalid-url))
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.190.0** (2025-05-22) — maintenance release, no component-specific changes
- **1.186.0** (2025-05-05) — maintenance release, no component-specific changes
- **1.185.0** (2025-04-30) — maintenance release, no component-specific changes
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.155.0** (2025-01-23) — fix: disable removing tags in a MultiSelect with readOnly mode ([#14472](invalid-url))
- **1.129.1** (2024-10-01) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.113.0** (2024-07-03) — feat: add customPrefix prop ([#13872](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes