---
title: Multi Select
docs:
  - route: /docs/components/tag-element
  - route: /docs/components/select-editor
---

<ComponentPreview name="select-editor-demo" />

<PackageInfo>

## Features

Unlike traditional input-based multi-selects, this component is built on top of Plate editor, providing:

- Full history support (undo/redo)
- Native cursor navigation between and within tags
- Select one to many tags
- Copy/paste tags
- Drag and drop to reorder tags
- Read-only mode
- Duplicate tags prevention
- Create new tags, case insensitive
- Search text cleanup
- Whitespace trimming
- Fuzzy search with [cmdk](https://github.com/pacocoursey/cmdk)

</PackageInfo>

## Installation

```bash
npm install @udecode/plate-tag
```

## Usage

```tsx
import { MultiSelectPlugin } from '@udecode/plate-tag/react';
import { TagElement } from '@/components/plate-ui/tag-element';
import {
  SelectEditor,
  SelectEditorContent,
  SelectEditorInput,
  SelectEditorCombobox,
  type SelectItem,
} from '@/components/plate-ui/select-editor';

// Define your items
const ITEMS: SelectItem[] = [
  { value: 'React' },
  { value: 'TypeScript' },
  { value: 'JavaScript' },
];

export default function MySelectEditor() {
  const [value, setValue] = React.useState<SelectItem[]>([ITEMS[0]]);

  return (
    <SelectEditor
      value={value}
      onValueChange={setValue}
      items={ITEMS}
    >
      <SelectEditorContent>
        <SelectEditorInput placeholder="Select items..." />
        <SelectEditorCombobox />
      </SelectEditorContent>
    </SelectEditor>
  );
}
```

- [TagElement](/docs/components/tag-element)
- [SelectEditor](/docs/components/select-editor)

## Plugins

### TagPlugin

Inline void element plugin.

### MultiSelectPlugin

Extension of the TagPlugin that constrains the editor to tag elements.

## API

### editor.tf.insert.tag

Inserts a new multi-select element at the current selection.

<APIParameters>
<APIItem name="props" type="TagLike">
Properties for the multi-select element:
<APISubList>
<APISubListItem parent="props" name="value" type="string">
The unique value of the multi-select element.
</APISubListItem>
</APISubList>
</APIItem>
</APIParameters>

## Hooks

### useSelectedItems

Hook to get the currently selected tag items in the editor.

<APIReturns>
  <APIItem type="TagLike[]">
    Array of selected tag items, each containing a value and any additional properties.
  </APIItem>
</APIReturns>

### getSelectedItems

Gets all tag items in the editor.

<APIParameters>
<APIItem name="editor" type="SlateEditor">
  The Slate editor instance.
</APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="TagLike[]">
    Array of tag items in the editor.
  </APIItem>
</APIReturns>

### isEqualTags

Utility function to compare two sets of tags for equality, ignoring order.

<APIParameters>
<APIItem name="editor" type="SlateEditor">
  The Slate editor instance.
</APIItem>
<APIItem name="newTags" type="TagLike[]" optional>
  New set of tags to compare against the current editor tags.
</APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="boolean">
    `true` if both sets contain the same values, `false` otherwise.
  </APIItem>
</APIReturns>

### useSelectableItems

Hook to get the available items that can be selected, filtered by search and excluding already selected items.

<APIParameters>
<APIItem name="options" type="object">
<APISubList>
<APISubListItem parent="options" name="allowNew" type="boolean" optional>
Whether to allow creating new items.

- **Default:** `true`
</APISubListItem>
<APISubListItem parent="options" name="filter" type="(value: string, search: string) => boolean" optional>
Custom filter function for items.
</APISubListItem>
<APISubListItem parent="options" name="items" type="T[]" optional>
Array of available items.
</APISubListItem>
<APISubListItem parent="options" name="newItemFilter" type="(search: string) => boolean" optional>
Filter function for new items.
</APISubListItem>
<APISubListItem parent="options" name="newItemPosition" type="'end' | 'start'" optional>
Position of new items in the list.

- **Default:** `'end'`
</APISubListItem>
</APISubList>
</APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="T[]">
    Filtered array of selectable items.
  </APIItem>
</APIReturns>

### useSelectEditorCombobox

Hook to handle combobox behavior in the editor, including text cleanup and item selection.

<APIParameters>
<APIItem name="options" type="object">
<APISubList>
<APISubListItem parent="options" name="open" type="boolean">
Whether the combobox is open.
</APISubListItem>
<APISubListItem parent="options" name="selectFirstItem" type="() => void">
Function to select the first item in the combobox.
</APISubListItem>
<APISubListItem parent="options" name="onValueChange" type="(items: TagLike[]) => void" optional>
Callback when selected items change.
</APISubListItem>
</APISubList>
</APIItem>
</APIParameters>

## Types

### TTagElement

```ts
type TTagElement = TElement & {
  value: string;
  [key: string]: unknown;
};
```

### TagLike

```ts
type TagLike = {
  value: string;
  [key: string]: unknown;
};
```