Docs
Cursor Overlay

Cursor Overlay

A visual overlay for cursors and selections.

Cursor Overlay
Loading...

The Cursor Overlay feature provides visual feedback for selections and cursor positions, particularly useful for maintaining context when the editor loses focus or during drag operations.

Features

  • Maintains selection highlight when another element is focused
  • Dynamic selection (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)

Installation

npm install @udecode/plate-selection

Usage

import { CursorOverlayPlugin } from '@udecode/plate-selection/react';
 
const plugins = [
  // ...otherPlugins,
  CursorOverlayPlugin,
];

Styling

  • CursorOverlay should be rendered inside the editor container. The containerRef is required to ensure the overlay is positioned correctly.
import { CursorOverlay } from '@/registry/default/plate-ui/cursor-overlay';
 
export function PlateEditor() {
  const containerRef = useRef(null);
  const editor = usePlateEditor();
 
  return (
    <Plate editor={editor}>
      <EditorContainer ref={containerRef} variant="demo">
        <Editor variant="demo" />
 
        <CursorOverlay containerRef={containerRef} />
      </EditorContainer>
    </Plate>
  );
}

Plugins

CursorOverlayPlugin

Plugin that manages cursor and selection overlays.

Options

Collapse all

    Object containing cursor states. Default: {}

API

editor.api.cursorOverlay.addCursor

Adds a cursor overlay with the specified key and state.

Parameters

Collapse all

    Unique identifier for the cursor (e.g., 'blur', 'drag', 'custom').

    The cursor state including selection and optional styling data.

editor.api.cursorOverlay.removeCursor

Removes a cursor overlay by its key.

Parameters

Collapse all

    The key of the cursor to remove.

API Components

CursorOverlay

Props

Collapse all

    Object containing cursor states for different interactions (blur, drag, etc.).

    Custom render function for cursor visualization.

Hooks

useCursorOverlayPositions

Returns cursor and selection positions for the current editor state.

CSVDate