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:T1322,--- title: Cursor Overlay description: Visual feedback for selections and cursor positions when editor loses focus. docs: - route: /docs/components/cursor-overlay title: Cursor Overlay --- ## Features - Maintains selection highlight when another element is focused. - Dynamic selection display (e.g., during AI streaming). - Shows cursor position during drag operations. - Customizable styling for cursors and selections. - Essential for external UI interactions (e.g., link toolbar, AI combobox). ## Kit Usage ### Installation The fastest way to add cursor overlay functionality is with the `CursorOverlayKit`, which includes the pre-configured `CursorOverlayPlugin` and the [`CursorOverlay`](/docs/components/cursor-overlay) UI component. - [`CursorOverlay`](/docs/components/cursor-overlay): Renders cursor and selection overlays. ### Add Kit ```tsx import { createPlateEditor } from 'platejs/react'; import { CursorOverlayKit } from '@/components/editor/plugins/cursor-overlay-kit'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ...CursorOverlayKit, ], }); ``` ## Manual Usage ### Installation ```bash npm install @platejs/selection ``` ### Add Plugin ```tsx import { CursorOverlayPlugin } from '@platejs/selection/react'; import { createPlateEditor } from 'platejs/react'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, CursorOverlayPlugin, ], }); ``` ### Configure Plugin Configure the cursor overlay with a component to render overlays: ```tsx import { CursorOverlayPlugin } from '@platejs/selection/react'; import { CursorOverlay } from '@/components/ui/cursor-overlay'; CursorOverlayPlugin.configure({ render: { afterEditable: () => , }, }); ``` - `render.afterEditable`: Assigns [`CursorOverlay`](/docs/components/cursor-overlay) to render after the editable content. ### Editor Container Setup The cursor overlay requires a container component to ensure correct positioning. If you're using the [Editor](/docs/components/editor) component, this is handled automatically through `EditorContainer`. For custom setups, ensure your editor is wrapped with a container that has the editor's unique ID: ```tsx import { PlateContainer } from 'platejs/react'; export function EditorContainer(props: React.HTMLAttributes) { return ; } ``` ### Preserving Selection Focus To maintain the editor's selection state when focusing UI elements, add the `data-plate-focus="true"` attribute to those elements: ```tsx {/* toolbar content */} ``` This prevents the cursor overlay from disappearing when interacting with toolbar buttons or other UI elements. ## Plugins ### `CursorOverlayPlugin` Plugin that manages cursor and selection overlays for visual feedback. Object containing cursor states with their unique identifiers. - **Default:** `{}` ## API ### `api.cursorOverlay.addCursor` Adds a cursor overlay with the specified key and state. Unique identifier for the cursor (e.g., 'blur', 'drag', 'custom'). The cursor state including selection and optional styling data. ### `api.cursorOverlay.removeCursor` Removes a cursor overlay by its key. The key of the cursor to remove. ## Hooks ### `useCursorOverlay` A hook that manages cursor and selection overlay states, providing real-time cursor positions and selection rectangles. Minimum width in pixels for a selection rectangle. Useful for making cursor carets more visible. - **Default:** `1` Whether to recalculate cursor positions when the container is resized. - **Default:** `true` Array of cursor states with their corresponding selection rectangles and styling data. Function to manually trigger a recalculation of cursor positions. 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)/(functionality)/cursor-overlay.mdx","content":"$50","type":"registry:file","target":"content/docs/plate/(plugins)/(functionality)/cursor-overlay.mdx"}],"className":"h-[70svh] min-h-80"}]]}]