Multi Select

PreviousNext
Tag NodeSelect Editor
Loading...

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 with case insensitive matching
  • Search text cleanup and whitespace trimming
  • Fuzzy search powered by cmdk

Manual Usage

Installation

pnpm add @platejs/tag

Add Plugins

import { MultiSelectPlugin } from '@platejs/tag/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    MultiSelectPlugin, // Multi-select editor with tag functionality
  ],
});

Configure Plugins

import { MultiSelectPlugin } from '@platejs/tag/react';
import { createPlateEditor } from 'platejs/react';
import { TagElement } from '@/components/ui/tag-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    MultiSelectPlugin.withComponent(TagElement),
  ],
});
  • MultiSelectPlugin: Extends TagPlugin and constrains the editor to only contain tag elements
  • withComponent: Assigns TagElement to render tag components

Add SelectEditor

npx shadcn@latest add https://platejs.org/r/select-editor

Basic Example

import { MultiSelectPlugin } from '@platejs/tag/react';
import { TagElement } from '@/components/ui/tag-node';
import {
  SelectEditor,
  SelectEditorContent,
  SelectEditorInput,
  SelectEditorCombobox,
  type SelectItem,
} from '@/components/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>
  );
}

Form Example

Plugins

TagPlugin

Inline void element plugin for individual tag functionality.

MultiSelectPlugin

Extension of TagPlugin that constrains the editor to only contain tag elements, enabling multi-select behavior with automatic text cleanup and duplicate prevention.

API

tf.insert.tag

Inserts new multi-select element at current selection.

Parameters

  • props TTagProps

    Properties for multi-select element.

OptionsTTagProps

Collapse all

  • value string

    Unique value of multi-select element.

getSelectedItems

Gets all tag items in the editor.

ReturnsTTagProps[]

    Array of tag items in editor.

isEqualTags

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

Parameters

Collapse all

  • newTags optional TTagProps[]

    New tags to compare against current editor tags.

Returnsboolean

    Whether both sets contain same values.

Hooks

useSelectedItems

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

ReturnsTTagProps[]

    Array of selected tag items with values and properties.

useSelectableItems

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

Optionsoptions

Collapse all

  • allowNew optional boolean

    Whether to allow creating new items.

    • Default: true

  • filter optional (value: string, search: string) => boolean

    Custom filter function for items.

  • items optional T[]

    Array of available items.

  • newItemFilter optional (search: string) => boolean

    Filter function for new items.

  • newItemPosition optional 'end' | 'start'

    Position of new items in list.

    • Default: 'end'

ReturnsT[]

    Filtered array of selectable items.

useSelectEditorCombobox

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

Optionsoptions

Collapse all

  • open boolean

    Whether combobox is open.

  • selectFirstItem () => void

    Function to select first combobox item.

  • onValueChange optional (items: TTagProps[]) => void

    Callback when selected items change.

Types

TTagElement

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

TTagProps

type TTagProps = {
  value: string;
  [key: string]: unknown;
};
多选可聚焦元素 (Tabbable)