Floating

---
title: Floating
description: API reference for floating UI components and hooks.
---

<PackageInfo>

## 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

</PackageInfo>

## Installation

```bash
npm install @platejs/floating
```

## API Hooks

### `useVirtualFloating`

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

<API name="useVirtualFloating">
<APIOptions type="UseVirtualFloatingOptions">
  <APIItem name="getBoundingClientRect" type="() => ClientRectObject" optional>
    Function to get the bounding client rect.
    - **Default:** Returns a zero-sized rect at (0,0)
  </APIItem>
  <APIItem name="open" type="boolean" optional>
    Controls visibility of the floating element.
  </APIItem>
  <APIItem name="whileElementsMounted" type="function" optional>
    Callback when elements are mounted.
    - **Default:** `autoUpdate` (updates on scroll and resize)
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="style" type="React.CSSProperties">
    Style object to apply to the floating element.
  </APIItem>
  <APIItem name="virtualElementRef" type="React.MutableRefObject">
    Reference to the virtual element.
  </APIItem>
  <APIItem name="refs" type="object">
    References for floating UI positioning.
  </APIItem>
  <APIItem name="update" type="() => void">
    Function to manually update positioning.
  </APIItem>
</APIReturns>
</API>

### `useFloatingToolbar`

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

<API name="useFloatingToolbar">
<APIOptions type="FloatingToolbarState">
  <APIItem name="floatingOptions" type="UseVirtualFloatingOptions" optional>
    Options passed to `useVirtualFloating`.
  </APIItem>
  <APIItem name="hideToolbar" type="boolean" optional>
    Force hide the toolbar.
  </APIItem>
  <APIItem name="showWhenReadOnly" type="boolean" optional>
    Show toolbar in read-only mode.
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="clickOutsideRef" type="React.RefObject">
    Ref to detect clicks outside the toolbar.
  </APIItem>
  <APIItem name="hidden" type="boolean">
    Whether the toolbar should be hidden.
  </APIItem>
  <APIItem name="props" type="object">
    Props to spread on the toolbar element.
  </APIItem>
  <APIItem name="ref" type="React.RefObject">
    Ref to attach to the toolbar element.
  </APIItem>
</APIReturns>
</API>

## API

### `getBoundingClientRect`

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

<API name="getBoundingClientRect">
<APIParameters>
  <APIItem name="editor" type="Editor">
    The editor instance.
  </APIItem>
  <APIItem name="at" type="Location | Location[]" optional>
    The location(s) to get the bounding rectangle for. If not provided, uses the current editor selection.
  </APIItem>
</APIParameters>

<APIReturns type="DOMRect | undefined">
  The merged bounding client rectangle of all specified locations, or undefined if no valid rectangles found.
</APIReturns>
</API>

### `getDOMSelectionBoundingClientRect`

<API name="getDOMSelectionBoundingClientRect">
<APIReturns type="ClientRectObject">
  The bounding client rectangle of the DOM selection. Returns a zero-sized rect at (0,0) if no selection exists.
</APIReturns>
</API>

### `getRangeBoundingClientRect`

Gets the bounding client rectangle for a specific Plate range.

<API name="getRangeBoundingClientRect">
<APIParameters>
  <APIItem name="editor" type="Editor">
    The editor instance.
  </APIItem>
  <APIItem name="at" type="TRange | null">
    The Plate range to get the bounding rectangle for.
  </APIItem>
</APIParameters>

<APIReturns type="ClientRectObject">
  The bounding client rectangle of the range. Returns a zero-sized rect at (0,0) if the range is null or invalid.
</APIReturns>
</API>

### `getSelectionBoundingClientRect`

Gets the bounding client rectangle of the current editor selection.

<API name="getSelectionBoundingClientRect">
<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
</APIParameters>

<APIReturns type="ClientRectObject">
  The bounding client rectangle of the selection. Returns a zero-sized rect at (0,0) if the selection is not expanded.
</APIReturns>
</API>