4f: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"] 50:T2ec8,--- title: Suggestion docs: - route: https://pro.platejs.org/docs/examples/discussion title: Plus - route: /docs/components/suggestion-node title: Suggestion Leaf - route: /docs/components/suggestion-toolbar-button title: Suggestion Toolbar Button - route: /docs/components/block-suggestion title: Block suggestion - route: /docs/components/block-discussion title: Block discussion --- ## Features - **Text Suggestions:** Add suggestions as text marks with inline annotations - **Block Suggestions:** Create suggestions for entire blocks of content - **State Tracking:** Track suggestion state and user interactions - **Undo/Redo Support:** Full undo/redo support for suggestion changes - **Discussion Integration:** Works with discussion plugin for complete collaboration ## Kit Usage ### Installation The fastest way to add suggestion functionality is with the `SuggestionKit`, which includes pre-configured `SuggestionPlugin` and related components along with their [Plate UI](/docs/installation/plate-ui) components. - [`SuggestionLeaf`](/docs/components/suggestion-node): Renders suggestion text marks - [`BlockSuggestion`](/docs/components/block-suggestion): Renders block-level suggestions - [`SuggestionLineBreak`](/docs/components/suggestion-node): Handles line breaks in suggestions ### Add Kit ```tsx import { createPlateEditor } from 'platejs/react'; import { SuggestionKit } from '@/components/editor/plugins/suggestion-kit'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ...SuggestionKit, ], }); ``` ## Manual Usage ### Installation ```bash npm install @platejs/suggestion ``` ### Extend Suggestion Plugin Create the suggestion plugin with extended configuration for state management: ```tsx import { type ExtendConfig, isSlateEditor, isSlateElement, isSlateString, } from 'platejs'; import { type BaseSuggestionConfig, BaseSuggestionPlugin, } from '@platejs/suggestion'; import { createPlatePlugin, toTPlatePlugin } from 'platejs/react'; import { BlockSuggestion } from '@/components/ui/block-suggestion'; import { SuggestionLeaf } from '@/components/ui/suggestion-node'; export type SuggestionConfig = ExtendConfig< BaseSuggestionConfig, { activeId: string | null; hoverId: string | null; } >; export const suggestionPlugin = toTPlatePlugin( BaseSuggestionPlugin, ({ editor }) => ({ options: { activeId: null, currentUserId: 'alice', // Set your current user ID hoverId: null, }, render: { node: SuggestionLeaf, belowRootNodes: ({ api, element }) => { if (!api.suggestion!.isBlockSuggestion(element)) { return null; } return ; }, }, }) ); ``` - `options.activeId`: Currently active suggestion ID for visual highlighting - `options.currentUserId`: ID of the current user creating suggestions - `options.hoverId`: Currently hovered suggestion ID for hover effects - `render.node`: Assigns [`SuggestionLeaf`](/docs/components/suggestion-node) to render suggestion text marks - `render.belowRootNodes`: Renders [`BlockSuggestion`](/docs/components/block-suggestion) for block-level suggestions ### Add Click Handler Add click handling to manage active suggestion state: ```tsx export const suggestionPlugin = toTPlatePlugin( BaseSuggestionPlugin, ({ editor }) => ({ handlers: { // Unset active suggestion when clicking outside of suggestion onClick: ({ api, event, setOption, type }) => { let leaf = event.target as HTMLElement; let isSet = false; const unsetActiveSuggestion = () => { setOption('activeId', null); isSet = true; }; if (!isSlateString(leaf)) unsetActiveSuggestion(); while ( leaf.parentElement && !isSlateElement(leaf.parentElement) && !isSlateEditor(leaf.parentElement) ) { if (leaf.classList.contains(`slate-${type}`)) { const suggestionEntry = api.suggestion!.node({ isText: true }); if (!suggestionEntry) { unsetActiveSuggestion(); break; } const id = api.suggestion!.nodeId(suggestionEntry[0]); setOption('activeId', id ?? null); isSet = true; break; } leaf = leaf.parentElement; } if (!isSet) unsetActiveSuggestion(); }, }, // ... previous options and render }) ); ``` The click handler tracks which suggestion is currently active: - **Detects suggestion clicks**: Traverses DOM to find suggestion elements - **Sets active state**: Updates `activeId` when clicking on suggestions - **Clears state**: Unsets `activeId` when clicking outside suggestions - **Visual feedback**: Enables hover/active styling in suggestion components ### Add Plugins ```tsx import { createPlateEditor, createPlatePlugin } from 'platejs/react'; import { SuggestionLineBreak } from '@/components/ui/suggestion-node'; const suggestionLineBreakPlugin = createPlatePlugin({ key: 'suggestionLineBreak', render: { belowNodes: SuggestionLineBreak as any }, }); const editor = createPlateEditor({ plugins: [ // ...otherPlugins, suggestionPlugin, suggestionLineBreakPlugin, ], }); ``` - `render.belowNodes`: Renders [`SuggestionLineBreak`](/docs/components/suggestion-node) below nodes to handle line break suggestions ### Enable Suggestion Mode Use the plugin's API to control suggestion mode: ```tsx import { useEditorRef, usePluginOption } from 'platejs/react'; function SuggestionToolbar() { const editor = useEditorRef(); const isSuggesting = usePluginOption(suggestionPlugin, 'isSuggesting'); const toggleSuggesting = () => { editor.setOption(suggestionPlugin, 'isSuggesting', !isSuggesting); }; return ( ); } ``` ### Add Toolbar Button You can add [`SuggestionToolbarButton`](/docs/components/suggestion-toolbar-button) to your [Toolbar](/docs/toolbar) to toggle suggestion mode in the editor. ### Discussion Integration The suggestion plugin works with the [discussion plugin](/docs/discussion) for complete collaboration: ```tsx const editor = createPlateEditor({ plugins: [ // ...otherPlugins, discussionPlugin, suggestionPlugin.configure({ options: { currentUserId: 'alice', }, }), suggestionLineBreakPlugin, ], }); ``` ## Keyboard Shortcuts Add a suggestion on the selected text. ## Plate Plus ## Plugins ### `SuggestionPlugin` Plugin for creating and managing text and block suggestions with state tracking and discussion integration. ID of the current user creating suggestions. Required for proper suggestion attribution. Whether the editor is currently in suggestion mode. Used internally to track state. ## API ### `api.suggestion.dataList` Gets suggestion data from a text node. The suggestion text node. Array of suggestion data. ### `api.suggestion.isBlockSuggestion` Checks if a node is a block suggestion element. The node to check. Whether the node is a block suggestion. ### `api.suggestion.node` Gets a suggestion node entry. Options for finding the node. The suggestion node entry if found. ### `api.suggestion.nodeId` Gets the ID of a suggestion from a node. The node to get ID from. The suggestion ID if found. ### `api.suggestion.nodes` Gets all suggestion node entries matching the options. Options for finding the nodes. Array of suggestion node entries. ### `api.suggestion.suggestionData` Gets suggestion data from a node. The node to get suggestion data from. The suggestion data if found. ### `api.suggestion.withoutSuggestions` Temporarily disables suggestions while executing a function. The function to execute. ## Types ### `TSuggestionText` Text nodes that can contain suggestions. Whether this is a suggestion. Suggestion data. Multiple suggestions can exist in one text node. ### `TSuggestionElement` Block elements that contain suggestion metadata. Block-level suggestion data including type, user, and timing information. ### `TInlineSuggestionData` Data structure for inline text suggestions. Unique identifier for the suggestion. ID of the user who created the suggestion. Timestamp when the suggestion was created. Type of suggestion operation. For update suggestions, the new mark properties being suggested. For update suggestions, the previous mark properties. ### `TSuggestionData` Data structure for block-level suggestions. Unique identifier for the suggestion. ID of the user who created the suggestion. Timestamp when the suggestion was created. Type of block suggestion operation. Whether this suggestion represents a line break insertion. 4e:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4f",null,{"files":[{"path":"../../content/docs/(plugins)/(collaboration)/suggestion.mdx","content":"$50","type":"registry:file","target":"content/docs/plate/(plugins)/(collaboration)/suggestion.mdx"}],"className":"h-[70svh] min-h-80"}]]}]