Integrations / Floating UI

A caret reference for Floating UI.

Floating UI intentionally starts with reference geometry. Caret Geometry supplies that geometry for browser carets.

Caret Geometry tracks the caret. Your positioning engine tracks the world around it.

Minimal production pattern

One update function

Caret-local invalidation

observeCaretGeometry() covers typing, selection movement, composition and internal control scroll.

Environmental invalidation

autoUpdate() covers ancestor scroll, resize and layout movement. Both invoke the same positioning path.

Why `contextElement` matters

The virtual reference includes the real editable as its contextElement. A positioner can use that element to discover scroll and clipping ancestors and layout context. It does not tell the positioner that typing moved the caret—that is why caret observation remains separate.

Common mistakes

Only compute once

The initial placement is correct, then every change is stale.

Only auto-update

Scroll follows, but typing or arrow movement may not cause an environmental event.

Only observe the caret

Typing follows, but page or modal scroll leaves the popup stale.

Integration checklist

Create one virtual reference for the target lifecycle.
Position the popup relative to it.
Subscribe to caret-local and environmental changes.
Hide when getCaretRect() reports unavailable.
Disconnect both subscriptions.

Troubleshooting

Popup appears at the top-left: Do not position before a valid caret exists. Hide until geometry is available.
Popup follows the input edge, not the caret: Pass the caret virtual reference—not the input element—as the reference.
Popup follows typing but not page scroll: Add the positioning engine’s environmental auto-update.
Popup follows scroll but not arrow keys: Add observeCaretGeometry().

Floating UI is a site/dev integration dependency only. The Caret Geometry runtime remains dependency-free. Floating UI virtual element documentation →