4e:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 4f:T2205,--- title: Combobox docs: - route: /docs/components/inline-combobox title: Inline Combobox --- Insert mentions for users, pages, or any reference with `@` Quick access to editor commands and blocks with `/` Insert emojis with autocomplete using `:` ## Features - Utilities for creating trigger-based combobox functionality - Configurable trigger characters and patterns - Keyboard navigation and selection handling ## Create a Combobox Plugin ### Installation ```bash npm install @platejs/combobox ``` ### Create Input Plugin First, create an input plugin that will be inserted when the trigger is activated: ```tsx import { createSlatePlugin } from 'platejs'; const TagInputPlugin = createSlatePlugin({ key: 'tag_input', editOnly: true, node: { isElement: true, isInline: true, isVoid: true, }, }); ``` ### Create Main Plugin Create your main plugin using `withTriggerCombobox`: ```tsx import { createTSlatePlugin, type PluginConfig } from 'platejs'; import { type TriggerComboboxPluginOptions, withTriggerCombobox } from '@platejs/combobox'; type TagConfig = PluginConfig<'tag', TriggerComboboxPluginOptions>; export const TagPlugin = createTSlatePlugin({ key: 'tag', node: { isElement: true, isInline: true, isVoid: true }, options: { trigger: '#', triggerPreviousCharPattern: /^\s?$/, createComboboxInput: () => ({ children: [{ text: '' }], type: 'tag_input', }), }, plugins: [TagInputPlugin], }).overrideEditor(withTriggerCombobox); ``` - `node.isElement`: Defines this as an element node (not text) - `node.isInline`: Makes the tag element inline (not block) - `node.isVoid`: Prevents editing inside the tag element - `options.trigger`: Character that triggers the combobox (in this case `#`) - `options.triggerPreviousCharPattern`: RegExp pattern that must match the character before the trigger. `/^\s?$/` allows the trigger at the start of a line or after whitespace - `options.createComboboxInput`: Function that creates the input element node when the trigger is activated ### Create Component Create the input element component using `InlineCombobox`: ```tsx import { PlateElement, useFocused, useReadOnly, useSelected } from 'platejs/react'; import { InlineCombobox, InlineComboboxContent, InlineComboboxEmpty, InlineComboboxInput, InlineComboboxItem, } from '@/components/ui/inline-combobox'; import { cn } from '@/lib/utils'; const tags = [ { id: 'frontend', name: 'Frontend', color: 'blue' }, { id: 'backend', name: 'Backend', color: 'green' }, { id: 'design', name: 'Design', color: 'purple' }, { id: 'urgent', name: 'Urgent', color: 'red' }, ]; export function TagInputElement({ element, ...props }) { return ( No tags found {tags.map((tag) => ( { // Insert actual tag element editor.tf.insertNodes({ type: 'tag', tagId: tag.id, children: [{ text: tag.name }], }); }} > #{tag.name} ))} {props.children} ); } export function TagElement({ element, ...props }) { const selected = useSelected(); const focused = useFocused(); const readOnly = useReadOnly(); return ( #{element.value} {props.children} ); } ``` ### Add to Editor ```tsx import { createPlateEditor } from 'platejs/react'; import { TagPlugin, TagInputPlugin } from './tag-plugin'; import { TagElement, TagInputElement } from './tag-components'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, TagPlugin.configure({ options: { triggerQuery: (editor) => { // Disable in code blocks return !editor.api.some({ match: { type: 'code_block' } }); }, }, }).withComponent(TagElement), TagInputPlugin.withComponent(TagInputElement), ], }); ``` - `options.triggerQuery`: Optional function to conditionally enable/disable the trigger based on editor state ## Examples ## Options ### TriggerComboboxPluginOptions Configuration options for trigger-based combobox plugins. 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. 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. Function to cancel the input. Props for the input element. Function to remove the input node. ### useHTMLInputCursorState Hook for tracking cursor position in an HTML input element. Reference to the input element to track. Whether cursor is at the start of input. Whether cursor is at the end of input. 4d:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4e",null,{"files":[{"path":"../../content/docs/(plugins)/(functionality)/(combobox)/combobox.mdx","content":"$4f","type":"registry:file","target":"content/docs/plate/(plugins)/(functionality)/(combobox)/combobox.mdx"}],"className":"h-[70svh] min-h-80"}]]}]