āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/udecode/plate/(plugins)/(functionality)/cursor-overlay ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
title: Cursor Overlay description: Visual feedback for selections and cursor positions when editor loses focus. docs:
The fastest way to add cursor overlay functionality is with the CursorOverlayKit, which includes the pre-configured CursorOverlayPlugin and the CursorOverlay UI component.
CursorOverlay: Renders cursor and selection overlays.import { createPlateEditor } from 'platejs/react';
import { CursorOverlayKit } from '@/components/editor/plugins/cursor-overlay-kit';
const editor = createPlateEditor({
plugins: [
// ...otherPlugins,
...CursorOverlayKit,
],
});
npm install @platejs/selection
import { CursorOverlayPlugin } from '@platejs/selection/react';
import { createPlateEditor } from 'platejs/react';
const editor = createPlateEditor({
plugins: [
// ...otherPlugins,
CursorOverlayPlugin,
],
});
Configure the cursor overlay with a component to render overlays:
import { CursorOverlayPlugin } from '@platejs/selection/react';
import { CursorOverlay } from '@/components/ui/cursor-overlay';
CursorOverlayPlugin.configure({
render: {
afterEditable: () => <CursorOverlay />,
},
});
render.afterEditable: Assigns CursorOverlay to render after the editable content.The cursor overlay requires a container component to ensure correct positioning. If you're using the 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:
import { PlateContainer } from 'platejs/react';
export function EditorContainer(props: React.HTMLAttributes<HTMLDivElement>) {
return <PlateContainer {...props} />;
}
To maintain the editor's selection state when focusing UI elements, add the data-plate-focus="true" attribute to those elements:
<ToolbarButton data-plate-focus="true">
{/* toolbar content */}
</ToolbarButton>
This prevents the cursor overlay from disappearing when interacting with toolbar buttons or other UI elements.
</Steps>CursorOverlayPluginPlugin that manages cursor and selection overlays for visual feedback.
<API name="CursorOverlayPlugin"> <APIOptions> <APIItem name="cursors" type="Record<string, CursorState<CursorData>>"> Object containing cursor states with their unique identifiers. - **Default:** `{}` </APIItem> </APIOptions> </API>api.cursorOverlay.addCursorAdds a cursor overlay with the specified key and state.
<API name="addCursor"> <APIParameters> <APIItem name="key" type="string"> Unique identifier for the cursor (e.g., 'blur', 'drag', 'custom'). </APIItem> <APIItem name="cursor" type="CursorState<CursorData>"> The cursor state including selection and optional styling data. </APIItem> </APIParameters> </API>api.cursorOverlay.removeCursorRemoves a cursor overlay by its key.
<API name="removeCursor"> <APIParameters> <APIItem name="key" type="string"> The key of the cursor to remove. </APIItem> </APIParameters> </API>useCursorOverlayA hook that manages cursor and selection overlay states, providing real-time cursor positions and selection rectangles.
<API name="useCursorOverlay"> <APIOptions type="object"> <APIItem name="minSelectionWidth" type="number" optional> Minimum width in pixels for a selection rectangle. Useful for making cursor carets more visible. - **Default:** `1` </APIItem> <APIItem name="refreshOnResize" type="boolean" optional> Whether to recalculate cursor positions when the container is resized. - **Default:** `true` </APIItem> </APIOptions> <APIReturns type="object"> <APIItem name="cursors" type="CursorOverlayState<TCursorData>[]"> Array of cursor states with their corresponding selection rectangles and styling data. </APIItem> <APIItem name="refresh" type="() => void"> Function to manually trigger a recalculation of cursor positions. </APIItem> </APIReturns> </API>ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā