Combobox

Utilities for adding combobox to your editor.

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',
  extendEditor: withTriggerCombobox,
  // 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],
});

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-common/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-common/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-common/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

Parameters

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

Returns

Collapse all

    Function to cancel the input.

    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.

Returns

Collapse all

ColumnComments