Docs
Combobox

Combobox

Select options from a list of predefined values.

Features

  • Displays a combobox for selecting options from a set list.
  • Suitable for creating mentions, tags, or slash commands.
  • Works in conjunction with the Mention plugin.

Activation Conditions:

  • Collapsed text selection.
  • Cursor placement immediately after the trigger character.
  • Text without spaces follows the trigger character.

On Activation:

  • Sets id, text, and targetRange in the combobox store.

Installation

npm install @udecode/plate-combobox

Usage

import { createComboboxPlugin } from '@udecode/plate-combobox';
import { createMentionPlugin } from '@udecode/plate-mention';
 
const plugins = [
  // ...otherPlugins,
  createComboboxPlugin(),
  createMentionPlugin(),
];

Then render the combobox component inside Plate. You can use the Combobox component or create your own.

Keyboard Interactions

KeyDescription
ArrowDown

Highlights the next item in the list.

ArrowUp

Highlights the previous item in the list.

EscCloses the combobox.
Tab

Selects the currently highlighted item.

Enter

Selects the currently highlighted item.

API

createComboboxPlugin

ComboboxProps

Here are some key aspects of the Combobox:

  • Multiple Instances: You can render the Combobox multiple times, each with its unique configuration provided by a different ComboboxStateById.
  • Singleton Behavior: Only one Combobox can be opened at a time. The state of the active Combobox is stored in the comboboxStore.
  • Extends ComboboxState, ComboboxStateById:

Parameters

Collapse all

    The items for the combobox. An alternative to setting the items is to use comboboxActions.items(items).

    A component that is rendered when the combobox is open. Useful for injecting hooks.

    A function to render the combobox item.

    • Default: item text

    The element to which the combobox is rendered.

    • Default: document.body

ComboboxState

Represents a combobox's state. The state resides in comboboxStore, which uses the zustood store.

Parameters

Collapse all

    Opened combobox ID.

    A collection of combobox configuration stores, each identified by a unique combobox ID (e.g., one for tags, one for mentions).

    • ComboboxStateById:

    The list of unfiltered items.

    The list of filtered items.

    The index of the currently highlighted item.

    The range from the trigger to the cursor.

    The text that appears after the trigger.

TComboboxItem

The data structure representing a single item in a combobox.

Parameters

Collapse all

    A unique key for the item.

    The text of the item.

    Indicates whether the item is disabled.

    • Default: false

    Data available to onRenderItem.

API Components

useComboboxContent

A behavior hook for the ComboboxContent component.

State

Collapse all

    The items for the combobox.

    The combobox store.

Returns

Collapse all

    The menu props for the combobox content.

    The target range of the combobox.

CollaborationComments