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:T1bf1,--- title: Emoji description: Inline emoji search and toolbar emoji picking. docs: - route: /docs/combobox title: Combobox - route: /docs/components/emoji-node title: Emoji Input Element - route: /docs/components/emoji-toolbar-button title: Emoji Toolbar Button --- Emoji adds two insertion paths: a `:` trigger that opens an inline combobox, and a toolbar popover for browsing categories. The package owns emoji data, trigger behavior, index search, picker state, frequent emoji storage, and insertion. The registry owns the inline input element and toolbar picker UI. ## Features - `:` trigger powered by `@platejs/combobox`. - Edit-only inline void `emoji_input` node. - Emoji search from `@emoji-mart/data`. - Default insertion as Unicode text. - Custom inserted node support through `createEmojiNode`. - Toolbar popover with categories, search, preview, and frequent emoji tracking. - Markdown shortcode deserialization to Unicode text. ## Fast Path ### Add The Kit `EmojiKit` installs `EmojiPlugin` with `@emoji-mart/data` and renders `EmojiInputPlugin` with the registry inline combobox. ```tsx import { createPlateEditor } from 'platejs/react'; import { EmojiKit } from '@/components/editor/plugins/emoji-kit'; export const editor = createPlateEditor({ plugins: EmojiKit, }); ``` ### Render The Inline Input `emoji-node` debounces the search text, queries `EmojiInlineIndexSearch`, and inserts the selected emoji. ### Add Toolbar Picking `emoji-toolbar-button` renders the Radix popover picker backed by `useEmojiDropdownMenuState`. ## Ownership | Layer | Owner | What It Does | |-------|-------|--------------| | `@platejs/emoji` | Package | Exports `BaseEmojiPlugin`, `BaseEmojiInputPlugin`, `insertEmoji`, emoji search libraries, settings, categories, and types. | | `@platejs/emoji/react` | Package | Exports `EmojiPlugin`, `EmojiInputPlugin`, picker hooks, and frequent emoji storage. | | `@platejs/combobox` | Package | Provides trigger detection and transient input cleanup for the `:` flow. | | `@emoji-mart/data` | Dependency | Provides the emoji dataset used by the registry kit. | | `emoji-kit` | Registry | Adds `EmojiPlugin` with emoji-mart data and `EmojiInputPlugin.withComponent(EmojiInputElement)`. | | `emoji-node` | Registry UI | Renders inline emoji search with `InlineCombobox`. | | `emoji-toolbar-button` | Registry UI | Renders the toolbar popover, category grid, search bar, and preview. | | `inline-combobox` | Registry UI | Renders the inline trigger input and popover primitives. | | `@platejs/markdown` | Package | Deserializes emoji shortcodes such as `:fire:` to Unicode text. | The emoji plugin is edit-only. It inserts text or your custom node, then the transient `emoji_input` disappears. ## Manual Setup ### Install Packages ```bash npm install @platejs/emoji @emoji-mart/data ``` ### Add Plugins Use `@emoji-mart/data` when you want the full emoji dataset instead of the package default library. ```tsx import emojiMartData from '@emoji-mart/data'; import { EmojiInputPlugin, EmojiPlugin } from '@platejs/emoji/react'; import { createPlateEditor } from 'platejs/react'; import { EmojiInputElement } from '@/components/ui/emoji-node'; export const editor = createPlateEditor({ plugins: [ EmojiPlugin.configure({ options: { data: emojiMartData as any, }, }), EmojiInputPlugin.withComponent(EmojiInputElement), ], }); ``` ### Add A Toolbar Button Render `EmojiToolbarButton` in your toolbar when users should browse emoji without typing `:`. ```tsx import { EmojiToolbarButton } from '@/components/ui/emoji-toolbar-button'; export function FixedToolbarButtons() { return ; } ``` ## Inline Flow The inline path is a combobox flow. | Step | Source | |------|--------| | Type `:` | `BaseEmojiPlugin` trigger. | | Previous character must match `/^\s?$/` | Start of block or whitespace by default. | | Insert transient input | `createComboboxInput` creates `{ type: KEYS.emojiInput, children: [{ text: '' }] }`. | | Search emoji data | `EmojiInputElement` calls `EmojiInlineIndexSearch.getInstance(data).search(query).get()`. | | Select a result | `InlineComboboxItem` removes the input and calls `insertEmoji(editor, emoji)`. | | Insert final content | `insertEmoji` calls `createEmojiNode(emoji)` and inserts that node. | `EmojiInputElement` sets `filter={false}` because emoji search already returns filtered results. It also uses `hideWhenNoValue`, so the popover stays closed until the user types a search value after `:`. ## Inserted Value By default, selecting an emoji inserts the first native skin as text. ```tsx EmojiPlugin.configure({ options: { createEmojiNode: ({ skins }) => ({ text: skins[0].native }), }, }); ``` Use `createEmojiNode` when your app stores emoji as structured inline nodes instead of text. ```tsx EmojiPlugin.configure({ options: { createEmojiNode: (emoji) => ({ children: [{ text: emoji.id }], emojiId: emoji.id, type: 'emoji-chip', }), }, }); ``` ## Toolbar Picker `EmojiToolbarButton` calls `useEmojiDropdownMenuState`, then passes the picker state into `EmojiPicker`. | Option | Default | Use | |--------|---------|-----| | `closeOnSelect` | `true` | Close the toolbar popover after insertion. | | `settings` | `EmojiSettings` | Configure categories, per-line count, button size, and frequent emoji behavior. | | `settings.showFrequent.limit` | Package setting | Limits the frequent emoji category. | Frequent emoji counts are stored in `window.localStorage` through `FrequentEmojiStorage`. On the server, the storage class returns the default frequent set. ## Markdown `@platejs/markdown` deserializes emoji shortcodes to Unicode text. ```md Launch :fire: soon ``` Serializing the resulting value writes the Unicode emoji: ```md Launch 🔥 soon ``` ## API Reference | API | Package | Use | |-----|---------|-----| | `BaseEmojiPlugin` | `@platejs/emoji` | Edit-only trigger plugin with default `:`, emoji data, input creation, and text insertion. | | `BaseEmojiInputPlugin` | `@platejs/emoji` | Edit-only inline void `emoji_input` plugin. | | `EmojiPlugin` | `@platejs/emoji/react` | React emoji plugin with nested `EmojiInputPlugin`. | | `EmojiInputPlugin` | `@platejs/emoji/react` | React input plugin for `EmojiInputElement`. | | `insertEmoji(editor, emoji)` | `@platejs/emoji` | Inserts `createEmojiNode(emoji)`. | | `EmojiInlineIndexSearch` | `@platejs/emoji` | Inline search index used by `emoji-node`. | | `useEmojiDropdownMenuState(options?)` | `@platejs/emoji/react` | Builds toolbar popover state and picker state. | | `useEmojiPicker(options)` | `@platejs/emoji/react` | Handles search, category focus, preview, selection, and frequent emoji updates. | | `FrequentEmojiStorage` | `@platejs/emoji/react` | Reads and writes frequent emoji counts through localStorage. | 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)/emoji.mdx","content":"$4f","type":"registry:file","target":"content/docs/plate/(plugins)/(functionality)/(combobox)/emoji.mdx"}],"className":"h-[70svh] min-h-80"}]]}]