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:T70c6,--- title: AI description: AI-powered writing assistance. docs: - route: https://pro.platejs.org/docs/examples/ai title: Plus --- ## Features - **Context-aware command menu** that adapts to cursor, text selection, and block selection workflows. - **Streaming Markdown/MDX insertion** with table, column, and code block support powered by `streamInsertChunk`. - **Insert and chat review modes** with localized insert previews plus undo-safe batching via `withAIBatch` and `tf.ai.undo()`. - **Block selection aware transforms** to replace or append entire sections using `tf.aiChat.replaceSelection` and `tf.aiChat.insertBelow`. - **Direct integration with `@ai-sdk/react`** so `api.aiChat.submit` can stream responses from Vercel AI SDK helpers. - **Suggestion and comment utilities** that diff AI edits, accept/reject changes, and map AI feedback back to document ranges. ## Kit Usage ### Installation The fastest way to add AI functionality is with the `AIKit`. It ships the configured `AIPlugin`, `AIChatPlugin`, Markdown streaming helpers, cursor overlay, and their [Plate UI](/docs/installation/plate-ui) components. - [`AIMenu`](/docs/components/ai-menu): Floating command surface for prompts, tool shortcuts, and chat review. - [`AILoadingBar`](/docs/components/ai-loading-bar): Displays streaming status at the editor container. - [`AIAnchorElement`](/docs/components/ai-anchor-element): Invisible anchor node used to position the floating menu during streaming. - [`AILeaf`](/docs/components/ai-leaf): Renders AI-marked text with subtle styling. ### Add Kit ```tsx import { createPlateEditor } from 'platejs/react'; import { AIKit } from '@/components/editor/plugins/ai-kit'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ...AIKit, ], }); ``` ### Add API Route Expose a streaming command endpoint that proxies your model provider: ### Configure Credentials For bring-your-own-key (BYOK) usage, enter your AI Gateway key in the editor settings or pass it as `apiKey` in the request body. The browser sends the caller's own key to the API route, which uses it for that request. For a shared application credential, authenticate and authorize each request, enforce per-user usage limits, and load the key on the server. Keep that shared key out of client code and request bodies. ## Manual Usage ### Installation ```bash npm install @platejs/ai @platejs/markdown @platejs/selection @ai-sdk/react ai ``` `@platejs/suggestion` is optional but required for diff-based edit suggestions. ### Add Plugins ```tsx import { createPlateEditor } from 'platejs/react'; import { AIChatPlugin, AIPlugin } from '@platejs/ai/react'; import { BlockSelectionPlugin } from '@platejs/selection/react'; import { MarkdownPlugin } from '@platejs/markdown'; export const editor = createPlateEditor({ plugins: [ BlockSelectionPlugin, MarkdownPlugin, AIPlugin, AIChatPlugin, // extended in the next step ], }); ``` - `BlockSelectionPlugin`: Enables multi-block selections that `AIChatPlugin` relies on for insert/replace transforms. - `MarkdownPlugin`: Provides Markdown serialization used by streaming utilities. - `AIPlugin`: Adds the AI mark and transforms for undoing AI batches. - `AIChatPlugin`: Supplies the AI combobox, API helpers, and transforms. Use `AIPlugin.withComponent` with your own element (or [`AILeaf`](/docs/components/ai-leaf)) to highlight AI-generated text. ### Configure AIChatPlugin Extend `AIChatPlugin` to hook streaming and edits. The example mirrors the core logic from `AIKit` while keeping the UI headless. ```tsx import cloneDeep from 'lodash/cloneDeep'; import { BaseAIPlugin, withAIBatch } from '@platejs/ai'; import { AIChatPlugin, applyAISuggestions, getInsertPreviewStart, streamInsertChunk, useChatChunk, } from '@platejs/ai/react'; import { ElementApi, getPluginType, KEYS, PathApi } from 'platejs'; import { usePluginOption } from 'platejs/react'; export const aiChatPlugin = AIChatPlugin.extend({ options: { chatOptions: { api: '/api/ai/command', body: { model: 'openai/gpt-4o-mini', }, }, trigger: ' ', triggerPreviousCharPattern: /^\s?$/, }, useHooks: ({ editor, getOption }) => { const mode = usePluginOption(AIChatPlugin, 'mode'); const toolName = usePluginOption(AIChatPlugin, 'toolName'); useChatChunk({ onChunk: ({ chunk, isFirst, text }) => { if (isFirst && mode === 'insert') { const { startBlock, startInEmptyParagraph } = getInsertPreviewStart(editor); editor.getTransforms(BaseAIPlugin).ai.beginPreview({ originalBlocks: startInEmptyParagraph && startBlock && ElementApi.isElement(startBlock) ? [cloneDeep(startBlock)] : [], }); editor.setOption(AIChatPlugin, 'streaming', true); editor.tf.withoutSaving(() => { editor.tf.insertNodes( { children: [{ text: '' }], type: getPluginType(editor, KEYS.aiChat), }, { at: PathApi.next(editor.selection!.focus.path.slice(0, 1)), } ); }); } if (mode === 'insert') { editor.tf.withoutSaving(() => { if (!getOption('streaming')) return; editor.tf.withScrolling(() => { streamInsertChunk(editor, chunk, { textProps: { [getPluginType(editor, KEYS.ai)]: true, }, }); }); }); } if (toolName === 'edit' && mode === 'chat') { withAIBatch( editor, () => { applyAISuggestions(editor, text); }, { split: isFirst } ); } }, onFinish: () => { editor.setOption(AIChatPlugin, 'streaming', false); editor.setOption(AIChatPlugin, '_blockChunks', ''); editor.setOption(AIChatPlugin, '_blockPath', null); editor.setOption(AIChatPlugin, '_mdxName', null); }, }); }, }); ``` - `useChatChunk`: Watches `UseChatHelpers` status and yields incremental chunks. - `tf.ai.beginPreview`: Captures the rollback slice and selection for insert-mode preview before the first streamed chunk is written. - `streamInsertChunk`: Streams Markdown/MDX into the document, reusing the existing block when possible. - `applyAISuggestions`: Converts responses into transient suggestion nodes when `toolName === 'edit'`. - `withAIBatch`: Marks saved AI batches so suggestion review and accepted AI changes stay undo-safe. Provide your own `render` components (toolbar button, floating menu, etc.) when you extend the plugin. ### Build API Route Handle `api.aiChat.submit` requests on the server. Each request includes the chat `messages` from `@ai-sdk/react` and a `ctx` payload that contains the editor `children`, current `selection`, and last `toolName`. [Complete API example](https://github.com/udecode/plate-playground-template/blob/main/src/app/api/ai/command/route.ts) ```ts title="app/api/ai/command/route.ts" import { convertToModelMessages, createGateway, createUIMessageStreamResponse, streamText, toUIMessageStream, } from 'ai'; import { createSlateEditor } from 'platejs'; import { BaseEditorKit } from '@/registry/components/editor/editor-base-kit'; import { markdownJoinerTransform } from '@/registry/lib/markdown-joiner-transform'; export async function POST(req: Request) { const { apiKey: key, ctx, messages, model } = await req.json(); const apiKey = typeof key === 'string' ? key.trim() : ''; if (!apiKey) { return Response.json({ error: 'Missing AI Gateway API key.' }, { status: 401 }); } const editor = createSlateEditor({ plugins: BaseEditorKit, selection: ctx.selection, value: ctx.children, }); const gateway = createGateway({ apiKey, }); const result = streamText({ experimental_transform: markdownJoinerTransform(), instructions: ctx.toolName === 'edit' ? 'You are an editor that rewrites user text.' : undefined, messages: await convertToModelMessages(messages), model: gateway(model ?? 'openai/gpt-4o-mini'), }); return createUIMessageStreamResponse({ stream: toUIMessageStream({ originalMessages: messages, stream: result.stream, }), }); } ``` - `ctx.children` and `ctx.selection` are rehydrated into a Slate editor so you can build rich prompts (see [Prompt Templates](#prompt-templates)). - Forward model settings through `chatOptions.body`. In the BYOK flow shown above, include the caller's own key as `apiKey`; the browser sends it in the JSON payload. - For a shared application key, the client sends session credentials or a short-lived authorization token. Authorize the request and load the shared provider key on the server instead of accepting it from the browser. - Return a streaming response so `useChat` and `useChatChunk` can process tokens incrementally. ### Connect `useChat` Bridge the editor and your model endpoint with `@ai-sdk/react`. Store helpers on the plugin so transforms can reload, stop, or show chat state. ```tsx import { useEffect } from 'react'; import { type UIMessage, DefaultChatTransport } from 'ai'; import { type UseChatHelpers, useChat } from '@ai-sdk/react'; import { AIChatPlugin } from '@platejs/ai/react'; import { useEditorPlugin } from 'platejs/react'; type ChatMessage = UIMessage<{}, { toolName: 'comment' | 'edit' | 'generate'; comment?: unknown }>; export const useEditorAIChat = () => { const { editor, setOption } = useEditorPlugin(AIChatPlugin); const chat = useChat({ id: 'editor', api: '/api/ai/command', transport: new DefaultChatTransport(), onData(data) { if (data.type === 'data-toolName') { editor.setOption(AIChatPlugin, 'toolName', data.data); } }, }); useEffect(() => { setOption('chat', chat as UseChatHelpers); }, [chat, setOption]); return chat; }; ``` Combine the helper with `useEditorChat` to keep the floating menu anchored correctly: ```tsx import { useEditorChat } from '@platejs/ai/react'; useEditorChat({ onOpenChange: (open) => { if (!open) chat.stop?.(); }, }); ``` Now you can submit prompts programmatically: ```tsx import { AIChatPlugin } from '@platejs/ai/react'; editor.getApi(AIChatPlugin).aiChat.submit('', { prompt: { default: 'Continue the document after {block}', selecting: 'Rewrite {selection} with a clearer tone', }, toolName: 'generate', }); ``` ## Prompt Templates ### Client Prompting - `api.aiChat.submit` accepts an `EditorPrompt`. Provide a string, an object with `default`/`selecting`/`blockSelecting`, or a function that receives `{ editor, isSelecting, isBlockSelecting }`. The helper `getEditorPrompt` in the client turns that value into the final string. - Combine it with `replacePlaceholders(editor, template, { prompt })` to expand `{editor}`, `{block}`, `{blockSelection}`, and `{prompt}` using Markdown generated by `@platejs/ai`. ```tsx import { replacePlaceholders } from '@platejs/ai'; editor.getApi(AIChatPlugin).aiChat.submit('Improve tone', { prompt: ({ isSelecting }) => isSelecting ? replacePlaceholders(editor, 'Rewrite {blockSelection} using a friendly tone.') : replacePlaceholders(editor, 'Continue {block} with two more sentences.'), toolName: 'generate', }); ``` ### Server Prompting The demo backend in `apps/www/src/app/api/ai/command` reconstructs the editor from `ctx` and builds structured prompts: - `getChooseToolPrompt` decides whether the request is `generate`, `edit`, or `comment`. - `getGeneratePrompt`, `getEditPrompt`, and `getCommentPrompt` transform the current editor state into instructions tailored to each mode. - Utility helpers like `getMarkdown`, `getMarkdownWithSelection`, and `buildStructuredPrompt` (see `apps/www/src/app/api/ai/command/prompts.ts`) make it easy to embed block ids, selections, and MDX tags into the LLM request. Augment the payload you send from the client to fine-tune server prompts: ```ts editor.setOption(aiChatPlugin, 'chatOptions', { api: '/api/ai/command', body: { model: 'openai/gpt-4o-mini', tone: 'playful', temperature: 0.4, }, }); ``` Everything under `chatOptions.body` arrives in the route handler, letting you swap providers, pass user-specific metadata, or branch into different prompt templates. ## Keyboard Shortcuts Open the AI menu in an empty block (cursor mode) Show the AI menu (set via `shortcuts.show`) Hide the AI menu and stop streaming ## Streaming The streaming utilities keep complex layouts intact while responses arrive: - `streamInsertChunk(editor, chunk, options)` deserializes Markdown chunks, updates the current block in place, and appends new blocks as needed. Use `textProps`/`elementProps` to tag streamed nodes (e.g., mark AI text). - `streamDeserializeMd` and `streamDeserializeInlineMd` provide lower-level access if you need to control streaming for custom node types. - `streamSerializeMd` mirrors the editor state so you can detect drift between streamed content and the response buffer. Reset the internal `_blockChunks`, `_blockPath`, and `_mdxName` options when streaming finishes to start the next response from a clean slate. ## Streaming Example ## Plate Plus ## API Reference ### `AIPlugin` Adds an `ai` mark to streamed text and exposes transforms to remove AI nodes or undo the last AI batch. Use `.withComponent` to render AI-marked text with a custom component. AI content is stored on text nodes. AI marks are regular text properties, not decorations. ### `AIChatPlugin` Main plugin that powers the AI menu, chat state, and transforms. Character(s) that open the command menu. Defaults to `' '`. Pattern that must match the character before the trigger. Defaults to `/^\s?$/`. Return `false` to cancel opening in specific contexts. Store helpers from `useChat` so API calls can access them. Snapshot of nodes used to diff edit suggestions (managed internally). Selection captured before submitting a prompt (managed internally). Controls whether responses stream directly into the document or open a review panel. Defaults to `'insert'`. Whether the AI menu is visible. Defaults to `false`. True while a response is streaming. Defaults to `false`. Active tool used to interpret the response. ### `api.aiChat.submit(input, options?)` Submits a prompt to your model provider. When `mode` is omitted it defaults to `'insert'` for a collapsed cursor and `'chat'` otherwise. Raw input from the user. Fine-tune submission behaviour. Override the response mode. Forwarded to `chat.sendMessage` (model, headers, etc.). String, config, or function processed by `getEditorPrompt`. Tags the submission so hooks can react differently. ### `api.aiChat.reset(options?)` Clears chat state, removes AI nodes, and optionally undoes the last AI batch. Pass `undo: false` to keep streamed content. ### `api.aiChat.node(options?)` Retrieves the first AI node that matches the specified criteria. Set `anchor: true` to get the anchor node or `streaming: true` to retrieve the node currently being streamed into. Matching node entry, if found. ### `api.aiChat.reload()` Replays the last prompt using the stored `UseChatHelpers`, restoring the original selection or block selection before resubmitting. ### `api.aiChat.stop()` Stops streaming and calls `chat.stop`. ### `api.aiChat.show()` Opens the AI menu, clears previous chat messages, and resets tool state. ### `api.aiChat.hide(options?)` Closes the AI menu, optionally undoing the last AI batch and refocusing the editor. Set `focus: false` to keep focus outside the editor or `undo: false` to preserve inserted content. ### `tf.aiChat.accept()` Accepts the latest response. In insert mode it removes AI marks and places the caret at the end of the streamed content. In chat mode it applies the pending suggestions. ### `tf.aiChat.insertBelow(sourceEditor, options?)` Inserts the chat preview (`sourceEditor`) below the current selection or block selection. Editor containing the generated content. Copy formatting from the source selection. Defaults to `'single'`. ### `tf.aiChat.replaceSelection(sourceEditor, options?)` Replaces the current selection or block selection with the chat preview. Editor containing the generated content. Controls how much formatting from the original selection should be applied. ### `tf.aiChat.removeAnchor(options?)` Removes the temporary anchor node used to position the AI menu. Filters the nodes to remove. ### `tf.ai.insertNodes(nodes, options?)` Inserts nodes tagged with the AI mark at the current selection (or `options.target`). ### `tf.ai.removeMarks(options?)` Clears the AI mark from matching nodes. ### `tf.ai.removeNodes(options?)` Removes text nodes that are marked as AI-generated. ### `tf.ai.beginPreview(options?)` Captures the rollback slice and selection for insert-mode AI preview. Call it once before writing the first unsaved preview chunk. Top-level blocks that the preview will overwrite. Use `[]` when preview inserts after existing content. Returns `true` when a new preview rollback point was stored, or `false` when preview state already exists. ### `tf.ai.acceptPreview()` Commits the active preview as one fresh undoable batch, strips preview-only markers, and clears preview bookkeeping. Returns `true` when an active preview was committed. ### `tf.ai.cancelPreview()` Restores the rollback point for the active preview and clears preview bookkeeping. Returns `true` when an active preview was restored. ### `tf.ai.discardPreview()` Clears preview bookkeeping without restoring content. Use it when the previewed content should stay in place. Returns `true` when active preview bookkeeping was cleared. ### `tf.ai.hasPreview()` Reports whether an insert-mode preview rollback point is currently active. Returns `true` when preview rollback state exists. ### `tf.ai.undo()` Undoes the latest AI history entry when it was created by `withAIBatch`. If an insert-mode preview is active, it cancels that preview first instead of replaying every streamed chunk. In both cases it avoids re-applying AI output from redo. ### `useAIChatEditor` Registers an auxiliary editor for chat previews and deserializes Markdown with block-level memoization. Editor instance dedicated to the chat preview. Markdown content returned by the model. Pass `parser` to filter tokens before deserialization. ```tsx import { usePlateEditor } from 'platejs/react'; import { MarkdownPlugin } from '@platejs/markdown'; import { AIChatPlugin, useAIChatEditor } from '@platejs/ai/react'; const aiPreviewEditor = usePlateEditor({ plugins: [MarkdownPlugin, AIChatPlugin], }); useAIChatEditor(aiPreviewEditor, responseMarkdown, { parser: { exclude: ['space'] }, }); ``` ### `useEditorChat` Connects `UseChatHelpers` to editor state so the AI menu knows whether to anchor to cursor, selection, or block selection. Called when the menu opens on block selection. Called whenever the menu opens or closes. Called when the menu opens at the cursor. Called when the menu opens on a text selection. ### `useChatChunk` Streams chat responses chunk-by-chunk and gives you full control over insertion. Handle each streamed chunk. Called when streaming finishes. ### `withAIBatch` Groups editor operations into a single history batch and flags it as AI-generated so `tf.ai.undo()` removes it safely. Target editor. Operations to run. Set `split: true` to start a new history batch. ### `applyAISuggestions` Diffs AI output against stored `chatNodes` and writes transient suggestion nodes. Requires `@platejs/suggestion`. Editor to apply suggestions to. Markdown response from the model. Complementary helpers allow you to finalize or discard the diff: - `acceptAISuggestions(editor)`: Converts transient suggestion nodes into permanent suggestions. - `rejectAISuggestions(editor)`: Removes transient suggestion nodes and clears suggestion marks. ### `aiCommentToRange` Maps streamed comment metadata back to document ranges so comments can be inserted automatically. Editor instance. Block id and text used to locate the range. Range matching the comment or `null` if it cannot be found. ### `findTextRangeInBlock` Fuzzy-search helper that uses LCS to find the closest match inside a block. Block node to search. Text snippet to locate. Matched range or `null`. ### `getEditorPrompt` Generates prompts that respect cursor, selection, or block selection states. Editor providing context. String, config, or function describing the prompt. Contextualized prompt string. ### `replacePlaceholders` Replaces placeholders like `{editor}`, `{blockSelection}`, and `{prompt}` with serialized Markdown. Editor providing content. Template text. Prompt value injected into `{prompt}`. Template with placeholders replaced by Markdown. ## Customization ### Adding Custom AI Commands Extend the `aiChatItems` map to add new commands. Each command receives `{ aiEditor, editor, input }` and can dispatch `api.aiChat.submit` with custom prompts or transforms. #### Simple Custom Command ```tsx summarizeInBullets: { icon: , label: 'Summarize in bullets', value: 'summarizeInBullets', onSelect: ({ editor }) => { void editor.getApi(AIChatPlugin).aiChat.submit('', { prompt: 'Summarize the current selection using bullet points', toolName: 'generate', }); }, }, ``` #### Command with Complex Logic ```tsx generateTOC: { icon: , label: 'Generate table of contents', value: 'generateTOC', onSelect: ({ editor }) => { const headings = editor.api.nodes({ match: (n) => ['h1', 'h2', 'h3'].includes(n.type as string), }); const prompt = headings.length === 0 ? 'Create a realistic table of contents for this document' : 'Generate a table of contents that reflects the existing headings'; void editor.getApi(AIChatPlugin).aiChat.submit('', { mode: 'insert', prompt, toolName: 'generate', }); }, }, ``` The menu automatically switches between command and suggestion states: - `cursorCommand`: Cursor is collapsed and no response yet. - `selectionCommand`: Text is selected and no response yet. - `cursorSuggestion` / `selectionSuggestion`: A response exists, so actions like Accept, Try Again, or Insert Below are shown. Use `toolName` (`'generate' | 'edit' | 'comment'`) to control how streaming hooks process the response. For example, `'edit'` enables diff-based suggestions, and `'comment'` allows you to convert streamed comments into discussion threads with `aiCommentToRange`. 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)/(ai)/ai.mdx","content":"$4f","type":"registry:file","target":"content/docs/plate/(plugins)/(ai)/ai.mdx"}],"className":"h-[70svh] min-h-80"}]]}]