Introduction
What is VFloat?
VFloat is a headless library for Vue 3.5 that provides composables for positioning and coordinating anchored floating elements, including tooltips, popovers, dropdown menus, context menus, and dialogs.
As a headless library, VFloat does not render components, HTML elements, or CSS styles. Instead, it provides reactive primitives that handle:
- Dynamic positioning and viewport collision detection (flipping, shifting, and boundary constraints)
- Synchronizing positions during window resize and container scroll
- User interaction triggers (hover, click, focus, outside clicks, and Escape key dismissal)
- Keyboard navigation (roving focus and focus containment)
- Multi-surface tree coordination for nested menus and stacked overlays
You retain full control over template markup, accessibility attributes, and styling.
The three core layers
Every floating surface in VFloat is assembled from three distinct steps: defining the node, calculating its position, and managing its open state.
1. Define the floating node
A floating surface connects two DOM elements: an anchor (such as a button) and a floating element (such as a tooltip).
The first step is creating a node that references both elements:
import { ref } from "vue";
import { useFloatingNode } from "v-float";
const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
const node = useFloatingNode({ anchorEl, floatingEl });
useFloatingNode creates the central state object for the surface. It stores the element references and tracks the reactive node.open boolean. It does not calculate coordinates or attach event listeners.
2. Position the floating element
Next, you pass the node to usePosition to calculate coordinates:
import { usePosition } from "v-float";
usePosition(node, {
placement: "top",
middlewares: { offset: 8 },
});
usePosition measures both elements, tracks container scroll and window resize events, and executes configured middlewares (such as offset, flip, and shift). By default, it applies the computed positioning styles directly to the floating element.
usePosition handles only placement and geometry. It does not control when the surface opens or closes.
3. Tell it when to open and close
To control visibility, attach interaction composables to the same node:
import { useEscapeKey, useHover } from "v-float";
useHover(node);
useEscapeKey(node);
Interaction composables listen for DOM events and toggle node.open. For example, useHover sets node.open to true when the cursor enters the anchor, and useEscapeKey sets it to false when the Escape key is pressed.
These composables manage only open and closed states. They do not interact with positioning calculations or styles.
Composing different surfaces
Because the three layers are decoupled, building different surfaces means combining different interaction composables with the same node architecture.
To build a basic tooltip, pair hover with Escape key dismissal:
useHover(node);
useEscapeKey(node);
To build a popover, replace hover with click and outside-click dismissal:
useClick(node);
useOutsideClick(node);
useEscapeKey(node);
To build a dropdown menu, add roving focus for keyboard navigation:
const itemEls = shallowRef<(HTMLElement | null)[]>([]);
useClick(node);
useOutsideClick(node);
useEscapeKey(node);
useRovingFocus(node, { elementsList: itemEls });
To build a modal dialog, add focus trapping:
useClick(node);
useFocusTrap(node, { modal: true });
useOutsideClick(node);
useEscapeKey(node);
Relationship to Floating UI
VFloat uses @floating-ui/dom under the hood for positioning calculations, collision detection, and middleware execution.
While Floating UI provides the official @floating-ui/vue package, that package is strictly a positioning wrapper for computePosition. It does not include interaction handlers, focus management, or dismissal behavior. In the React ecosystem, those features exist in @floating-ui/react, but Vue has lacked an equivalent comprehensive suite.
VFloat fills this gap for Vue 3.5. It combines Floating UI's positioning engine with:
- Interaction primitives: Composables for hover (with delay and safe polygon tracking), click triggers, outside-click detection, and Escape key dismissal.
- Focus and keyboard navigation: Built-in roving focus, active-descendant virtualization, typeahead search, and modal focus trapping.
- Tree coordination: Reactive parent-child relationships that synchronize nested submenus and stacked dialogs.
- Vue-native architecture: Decoupled composables connected by a shared reactive node (
useFloatingNode), with automatic style application on elements.
Where to go next
- Tutorial: Follow the First Tooltip guide to build your first floating interface step by step.
- Core Concepts: Understand the Floating Node, Positioning, Interaction Model, and Hierarchy.
- Positioning: Read about Middlewares and Virtual Anchors.
- Accessibility: Master ARIA & Semantics, Focus Models, Keyboard Navigation, and Hover & Dismissal.
- API Reference: Check the API Reference for complete composable signatures, options, and return values.