API Reference
VFloat provides composable primitives for building anchored floating interfaces in Vue 3. Each composable handles one focused responsibility: lifecycle and refs, positioning calculations, interaction listeners, accessibility semantics, or keyboard navigation.
Use the Guides to learn end-to-end workflows and architectural principles. Use these API reference pages when you need exact signatures, options, return shapes, and integration contracts.
Choose Primitives by Goal
Pick the combination of composables and middleware that matches your interface pattern:
| Interface Pattern | Primary Composables | Suggested Middleware | Guide |
|---|---|---|---|
| Tooltip | useFloatingNode, useHover, usePosition | offset, flip, shift, arrow | First Tooltip |
| Popover / Dropdown | useFloatingNode, useClick, useOutsideClick, useEscapeKey, usePosition | offset, flip, shift | First Menu |
| Dialog / Modal | useFloatingNode, useFocusTrap, useEscapeKey, useOutsideClick, useRole | None (CSS centered) | Focus Models |
| ContextMenu / Cursor | useFloatingNode, useClientPoint, useOutsideClick, useEscapeKey, usePosition | flip, shift | Virtual Anchors |
| Menu with Roving Focus | useFloatingNode, useRovingFocus, useClick, useOutsideClick, useEscapeKey | offset, flip, shift | Keyboard Navigation |
| Nested Menu Tree | useFloatingNode, useRovingFocus, useOutsideClick, useEscapeKey | offset, flip | Hierarchy |
| Combobox / Autocomplete | useAriaActivedescendant, useTypeahead, usePosition | offset, flip, size | Keyboard Navigation |
Core
Core primitives manage node identity, shared element references, open/close lifecycle, and composite tree hierarchies.
| Composable | Description |
|---|---|
useFloatingNode | Creates a composite floating node managing element refs, open state, and parent-child hierarchy. |
| Types | Canonical types, navigation protocols, and data structures exported by VFloat. |
Positioning
Positioning composables compute screen coordinates, run the middleware pipeline, listen to viewport changes, and generate style bindings.
| Composable | Description |
|---|---|
usePosition | Computes reactive coordinates and automatically applies inline positioning styles to the floating element. |
useArrow | Registers an arrow element with the positioning pipeline and automatically applies computed arrow styles. |
useClientPoint | Positions a floating element relative to pointer coordinates using a virtual anchor. |
Interactions
Interaction composables attach DOM event listeners to the anchor or document to open, close, and manage focus for floating surfaces.
| Composable | Description |
|---|---|
useClick | Toggles open state from click, tap, or keyboard activation on the anchor. |
useHover | Opens and closes floating content on pointer hover with delay and safe polygon tracking. |
useFocus | Opens and closes floating content when the anchor gains or loses keyboard focus. |
useFocusTrap | Manages modal focus containment, boundary sentinels, background isolation, and return focus. |
useOutsideClick | Closes open floating surfaces when pointer interactions occur outside the floating family. |
useEscapeKey | Closes open floating surfaces on Escape key presses with leaf-first hierarchy and IME coordination. |
useRole | Synchronizes ARIA roles, popup states, and accessibility relationships on anchor and panel. |
Keyboard Navigation
Primitives for managing keyboard navigation patterns in dropdowns, menus, and comboboxes.
| Composable | Description |
|---|---|
useRovingFocus | Moves physical DOM focus between elements in composite widgets using roving tabindex. |
useAriaActivedescendant | Virtual focus keeping DOM focus on an input while highlighting options via aria-activedescendant. |
useTypeahead | Captures rapid typing sequences to jump directly to matching items in a list. |
Middleware
Positioning middleware runs sequentially inside usePosition to modify placement, prevent collisions, add spacing, or measure boundary constraints.
Configure them declaratively inside usePosition(node, { middlewares: { ... } }) or pass middleware instances directly.
| Middleware | Pipeline Phase | Declarative Key | Description |
|---|---|---|---|
offset | 1. Distance | offset: 8 | Adds distance along the main and cross axes between anchor and panel. |
flip | 2. Collision | flip: true | Flips to the opposite or fallback placement when space is constrained. |
shift | 3. Boundary | shift: true | Nudges the floating element along its axis to remain inside the viewport. |
autoPlacement | 4. Placement | autoPlacement: true | Selects the placement with the greatest available space (alternative to flip). |
size | 5. Sizing | size: { apply } | Measures available space to resize or constrain panel dimensions. |
inline | 6. Geometry | inline: true | Positions relative to individual client rects for multi-line inline triggers. |
arrow | 7. Decorator | arrow: true | Positions an arrow element aligned with the anchor. |
hide | 8. Visibility | hide: true | Detects when the anchor is clipped or when the panel escapes its boundary. |
Conventions Across APIs
- Reactivity: Options accept plain values, Vue refs, or getter functions (
MaybeRefOrGetter<T>). Changes automatically re-evaluate active composables. - Node Coupling: Every composable in a floating surface accepts the same
FloatingNodecreated byuseFloatingNode. - Style Binding: By default (
applyStyles: true),usePositionanduseArrowautomatically synchronize positioning and arrow styles directly tonode.refs.floatingElandnode.refs.arrowEl. Alternatively, setapplyStyles: falseand bind:style="styles"or:style="arrowStyles"manually in templates.