Floating

PreviousNext

API reference for floating UI components and hooks.

Features

  • Virtual floating elements that follow cursor position
  • Floating toolbar that appears on text selection
  • Built on top of Floating UI
  • Customizable positioning and behavior
  • Automatic updates on scroll and resize

Installation

pnpm add @platejs/floating

API Hooks

useVirtualFloating

Creates a floating element with a controlled virtual element, typically used to follow cursor position.

OptionsUseVirtualFloatingOptions

  • getBoundingClientRect optional () => ClientRectObject

    Function to get the bounding client rect.

    • Default: Returns a zero-sized rect at (0,0)

  • open optional boolean

    Controls visibility of the floating element.

  • whileElementsMounted optional function

    Callback when elements are mounted.

    • Default: autoUpdate (updates on scroll and resize)

Returnsobject

Collapse all

  • style React.CSSProperties

    Style object to apply to the floating element.

  • virtualElementRef React.MutableRefObject

    Reference to the virtual element.

  • refs object

    References for floating UI positioning.

  • update () => void

    Function to manually update positioning.

useFloatingToolbar

Creates a floating toolbar that appears when text is selected in the editor.

OptionsFloatingToolbarState

Collapse all

  • floatingOptions optional UseVirtualFloatingOptions

    Options passed to useVirtualFloating.

  • hideToolbar optional boolean

    Force hide the toolbar.

  • showWhenReadOnly optional boolean

    Show toolbar in read-only mode.

Returnsobject

Collapse all

  • clickOutsideRef React.RefObject

    Ref to detect clicks outside the toolbar.

  • hidden boolean

    Whether the toolbar should be hidden.

  • props object

    Props to spread on the toolbar element.

  • ref React.RefObject

    Ref to attach to the toolbar element.

API

getBoundingClientRect

Gets the bounding client rectangle for a location or array of locations in the editor.

Parameters

Collapse all

  • editor Editor

    The editor instance.

  • at optional Location | Location[]

    The location(s) to get the bounding rectangle for. If not provided, uses the current editor selection.

ReturnsDOMRect | undefined

    The merged bounding client rectangle of all specified locations, or undefined if no valid rectangles found.

getDOMSelectionBoundingClientRect

ReturnsClientRectObject

    The bounding client rectangle of the DOM selection. Returns a zero-sized rect at (0,0) if no selection exists.

getRangeBoundingClientRect

Gets the bounding client rectangle for a specific Plate range.

Parameters

Collapse all

  • editor Editor

    The editor instance.

  • at TRange | null

    The Plate range to get the bounding rectangle for.

ReturnsClientRectObject

    The bounding client rectangle of the range. Returns a zero-sized rect at (0,0) if the range is null or invalid.

getSelectionBoundingClientRect

Gets the bounding client rectangle of the current editor selection.

Parameters

Collapse all

  • editor PlateEditor

    The editor instance.

ReturnsClientRectObject

    The bounding client rectangle of the selection. Returns a zero-sized rect at (0,0) if the selection is not expanded.

Plate CoreFloating