Skip to main content

Combobox

Installation#

npm install @udecode/plate-combobox

Combobox Store#

The combobox state is stored in a zustood store: comboboxStore.

ComboboxState#

  • activeId โ€“ Active id (combobox id which is opened)
  • byId โ€“ Object whose keys are combobox ids and values are combobox config stores (e.g. one for tag, one for mention,...)
  • items โ€“ Unfiltered items
  • filteredItems โ€“ Filtered items
  • highlightedIndex โ€“ Highlighted index
  • popperContainer โ€“ Parent element of the popper element (the one that has the scroll)
  • popperOptions โ€“ Overrides usePopper options
  • targetRange โ€“ Range from the trigger to the cursor
  • text โ€“ Text after the trigger

ComboboxStateById#

  • activeId โ€“ Combobox id
  • filter โ€“ Items filter function by text
  • maxSuggestions โ€“ Max number of items
  • trigger โ€“ Trigger that activates the combobox
  • onSelectItem โ€“ Called when an item is selected

Combobox Component#

  • can be rendered multiple times for each combobox configuration (ComboboxStateById)
  • singleton (only one combobox can be opened), its state is stored in comboboxStore

Props#

  • ComboboxStateById โ€“ the combobox config
  • items โ€“ Set items to the combobox store. Alternative: comboboxStore.set.items(items).
  • component โ€“ Render this component when the combobox is open (useful to inject hooks).
  • onRenderItem โ€“ Render combobox item (default is text)

Combobox Items#

Combobox items have the following interface:

export interface ComboboxItemData {
/**
* Unique key.
*/
key: string;
/**
* Item text.
*/
text: any;
/**
* Whether the item is disabled.
* @default false
*/
disabled?: boolean;
/**
* Data available to `onRenderItem`.
*/
data?: unknown;
}

Combobox plugin#

onChange:

For each combobox state:#

  • if the selection is collapsed
  • if the cursor follows the trigger
  • if there is text without whitespaces after the trigger
  • open the combobox: set id, text, targetRange in the store

onKeyDown#

If the combobox is open, handle:

  • down (next item)
  • up (previous item)
  • escape (reset combobox)
  • tab, enter (select item)

Source Code#