{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "api-floating-docs",
"title": "Floating",
"description": "API reference for @platejs/floating.",
"files": [
{
"path": "../../content/docs/api/floating.mdx",
"content": "---\ntitle: Floating\ndescription: API reference for @platejs/floating.\n---\n\n`@platejs/floating` contains the React hooks and rectangle utilities used by floating toolbars, cursor-anchored UI, and virtual elements in Plate. It wraps Floating UI and exports the Floating UI primitives Plate components use.\n\n## Installation\n\n```bash\nnpm install @platejs/floating\n```\n\n## Ownership\n\n| Surface | Owner | Use |\n| --- | --- | --- |\n| `useVirtualFloating` | `@platejs/floating` | `useFloating` with a controlled virtual reference element. |\n| `useFloatingToolbarState` | `@platejs/floating` | Builds toolbar state from editor focus, selection, read-only state, and Floating UI options. |\n| `useFloatingToolbar` | `@platejs/floating` | Turns toolbar state into DOM props, ref, outside-click ref, and hidden state. |\n| Rect utilities | `@platejs/floating` | Convert editor ranges, DOM selection, and client rect arrays into Floating UI-compatible rects. |\n| Floating UI exports | `@platejs/floating` | Re-exported middleware and hooks from `@floating-ui/react`. |\n\n## Virtual Floating\n\n`useVirtualFloating` creates a Floating UI virtual reference. Use it when the floating element follows a selection, cursor, or computed rectangle instead of a real DOM reference element.\n\n```tsx title=\"Virtual floating element\"\nimport {\n flip,\n getDefaultBoundingClientRect,\n offset,\n useVirtualFloating,\n} from '@platejs/floating';\n\nexport function SelectionPopover({\n open,\n rect,\n}: {\n open: boolean;\n rect?: DOMRect;\n}) {\n const floating = useVirtualFloating({\n getBoundingClientRect: () => rect ?? getDefaultBoundingClientRect(),\n middleware: [offset(8), flip()],\n open,\n placement: 'top',\n });\n\n return (\n \n Selection actions\n
\n );\n}\n```\n\n\n\n ClientRectObject\" optional>\n Supplies the virtual element rect. Defaults to `getDefaultBoundingClientRect`.\n \n \n When `false`, the returned style sets `display: 'none'`.\n \n \n Defaults to Floating UI `autoUpdate`.\n \n \" optional>\n Forwarded to Floating UI `useFloating`.\n \n\n\n \n Absolute/fixed position style: `position`, `left`, `top`, `display`, and `visibility`.\n \n \">\n Mutable virtual reference element. The hook updates its `getBoundingClientRect`.\n \n \n Floating UI refs. Attach `refs.setFloating` to the floating element.\n \n \n Floating UI manual position update.\n \n\n\n\n## Floating Toolbar\n\nFloating toolbar setup is split into two hooks. Build state first, then pass that state to `useFloatingToolbar`.\n\n```tsx title=\"Floating toolbar state\"\nimport {\n flip,\n offset,\n useFloatingToolbar,\n useFloatingToolbarState,\n} from '@platejs/floating';\nimport { useEditorId, useEventEditorValue } from 'platejs/react';\n\nexport function ToolbarShell() {\n const editorId = useEditorId();\n const focusedEditorId = useEventEditorValue('focus');\n\n const state = useFloatingToolbarState({\n editorId,\n focusedEditorId,\n floatingOptions: {\n middleware: [offset(12), flip({ padding: 12 })],\n placement: 'top',\n },\n });\n\n const { clickOutsideRef, hidden, props, ref } = useFloatingToolbar(state);\n\n if (hidden) return null;\n\n return (\n \n );\n}\n```\n\n\n\n \n Current editor id.\n \n \n Focused editor id from `useEventEditorValue('focus')`.\n \n \n Options passed to `useVirtualFloating`.\n \n \n Force the toolbar closed.\n \n \n Allow the toolbar to show when the editor is read-only.\n \n\n\">\n Internal toolbar state for `useFloatingToolbar`.\n\n\n\n\n\">\n \" required>\n State returned by `useFloatingToolbarState`.\n \n\n\n \">\n Ref from `useOnClickOutside`. It closes the toolbar and ignores `.ignore-click-outside/toolbar`.\n \n \n `true` when the toolbar should not render.\n \n \n Props to spread on the toolbar root.\n \n \n Floating element ref callback.\n \n\n\n\nThe toolbar opens only for an expanded selection with text. It stays hidden while the mouse is down, when `hideToolbar` is true, when a different editor owns focus, or when the editor is read-only and `showWhenReadOnly` is not set.\n\n## Rectangle Utilities\n\nThese helpers normalize editor locations and DOM ranges into rectangles.\n\n\n\n ClientRectObject\">\n Returns a zero-size offscreen rect used as a safe Floating UI fallback.\n \n VirtualElement\">\n Creates a Floating UI virtual element with `getDefaultBoundingClientRect`.\n \n VirtualRef\">\n Creates a ref-like object whose `current.getBoundingClientRect()` reads editor locations. It throws when no rect exists and no `fallbackRect` is provided.\n \n DOMRect | undefined\">\n Reads one or more editor locations, converts them to DOM ranges, and returns the merged bounding rect. If `at` is omitted, it uses `editor.selection`.\n \n ClientRectObject\">\n Returns the DOM rect for a range, or `getDefaultBoundingClientRect()` when the range or DOM range is missing.\n \n ClientRectObject\">\n Returns the selection rect only when the editor selection is expanded. Collapsed selections return the default rect.\n \n ClientRectObject\">\n Returns `window.getSelection().getRangeAt(0).getBoundingClientRect()`, or the default rect when no DOM selection exists.\n \n DOMRect\">\n Creates a DOMRect-like object and computes `width`, `height`, `x`, and `y`.\n \n DOMRect\">\n Merges client rects by min left/top and max right/bottom. It throws when the array is empty.\n \n\n\n\n## Floating UI Re-exports\n\n`@platejs/floating` re-exports the Floating UI middleware and React hooks used by Plate UI, including `autoUpdate`, `flip`, `hide`, `inline`, `offset`, `shift`, `size`, `useFloating`, `useInteractions`, `useClick`, `useDismiss`, `FloatingPortal`, and related types.\n\nUse those exports when a Plate UI component already imports from `@platejs/floating`; use `@floating-ui/react` directly only when the component is not coupled to Plate.\n\n## Related Components\n\n- [Toolbar](/docs/toolbar) covers the registry floating-toolbar component that consumes these hooks.\n- [Plate Store](/docs/api/core/plate-store) covers `useEditorId` and `useEventEditorValue`.\n",
"type": "registry:file",
"target": "content/docs/plate/api/floating.mdx"
}
],
"type": "registry:file"
}