Combobox

Mention PluginSlash Command PluginEmoji Plugin

The TriggerComboboxPluginOptions configures your plugin to insert a combobox input element when the user types a specified trigger character.

For example:

  • Mention plugin inserts a combobox when typing @
  • Slash Command plugin activates with /
  • Emoji plugin shows suggestions with :

Usage

Create an input plugin for the combobox:

const ComboboxInputPlugin = createPlatePlugin({
  key: 'combobox_input',
  node: {
    isElement: true,
    isInline: true,
    isVoid: true,
  },
});

Create your main plugin with withTriggerCombobox:

const MyPlugin = createPlatePlugin({
  key: 'my_plugin',
  // Plugin node options
  node: {
    isElement: true,
    isInline: true,
    isVoid: true,
  },
  // Combobox options
  options: {
    createComboboxInput: (trigger) => ({
      children: [{ text: '' }],
      trigger,
      type: ComboboxInputPlugin.key,
    }),
    trigger: '@',
    triggerPreviousCharPattern: /^\s?$/,
  },
  // Include the input plugin
  plugins: [ComboboxInputPlugin],
}).overrideEditor(withTriggerCombobox);

The input element component can be built using Inline Combobox.

Examples

Loading...
Files
components/demo.tsx
'use client';

import React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
Loading...
Files
components/demo.tsx
'use client';

import React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
Loading...
Files
components/demo.tsx
'use client';

import React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Types

TriggerComboboxPluginOptions

Attributes

Collapse all

    Function to create the input node when trigger is activated.

    Character(s) that trigger the combobox. Can be:

    • A single character (e.g. '@')
    • An array of characters
    • A regular expression

    Pattern to match the character before trigger.

    • Example: /^\s?$/ matches start of line or space

    Custom query function to control when trigger is active.

Hooks

useComboboxInput

Hook for managing combobox input behavior and keyboard interactions.

Parameters

Collapse all

    Options for the combobox input.

OptionsUseComboboxInputOptions

Collapse all

    Reference to the input element.

    Auto focus the input when mounted.

    • Default: true

    Cancel on arrow keys.

    • Default: true

    Cancel on backspace at start.

    • Default: true

    Cancel on blur.

    • Default: true

    Cancel when deselected.

    • Default: true

    Cancel on escape key.

    • Default: true

    Current cursor position state.

    Forward undo/redo to editor.

    • Default: true

    Callback when input is cancelled.

Returnsobject

Collapse all

    Function to cancel the input.

    Props for the input element.

    Function to remove the input node.

Example:

const MyCombobox = () => {
  const inputRef = useRef<HTMLInputElement>(null);
  const cursorState = useHTMLInputCursorState(inputRef);
 
  const { props: inputProps, removeInput } = useComboboxInput({
    ref: inputRef,
    cursorState,
    cancelInputOnBlur: false,
    onCancelInput: (cause) => {
      if (cause !== 'backspace') {
        insertText(editor, trigger + value);
      }
      if (cause === 'arrowLeft' || cause === 'arrowRight') {
        moveSelection(editor, {
          distance: 1,
          reverse: cause === 'arrowLeft',
        });
      }
    },
  });
 
  return <input ref={inputRef} {...inputProps} />;
};

useHTMLInputCursorState

Hook for tracking cursor position in an HTML input element.

Parameters

Collapse all

    Reference to the input element to track.

ReturnsComboboxInputCursorState

Collapse all

    Whether cursor is at the start of input.

    Whether cursor is at the end of input.