Floating node
A floating surface is rarely just one thing. It needs positioning, a trigger like hover or click, and dismissal like Escape or an outside click.
Instead of wiring element refs and open state through every composable manually, VFloat gives them a shared context: the FloatingNode.
The shared hub
useFloatingNode creates the node. It holds three things:
- Element refs:
anchorEl,floatingEl, and an optionalarrowEl. - Open state: a reactive
openboolean ref. - Hierarchy: parent and child links for nested surfaces.
The node itself does not position elements or listen to DOM events. It is just the shared state that companion composables plug into:
usePosition(node)reads the elements and open state to calculate coordinates.useHover(node)anduseClick(node)togglenode.open.useEscapeKey(node)anduseOutsideClick(node)closenode.open.
How it looks in practice
You create the node once and pass it to whatever composables the surface needs:
<script setup lang="ts">
import { ref } from "vue";
import { useEscapeKey, useFloatingNode, useHover, usePosition } from "v-float";
const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
// 1. Create the shared context
const node = useFloatingNode({ anchorEl, floatingEl });
// 2. Plug in positioning
usePosition(node, {
placement: "top",
middlewares: {
offset: 8,
},
});
// 3. Plug in interactions
useHover(node);
useEscapeKey(node);
</script>
<template>
<button ref="anchorEl" type="button">Hover me</button>
<div v-if="node.open.value" ref="floatingEl" class="tooltip">Tooltip text</div>
</template>
When useHover detects pointer entry, it sets node.open.value = true. That renders the tooltip, which causes usePosition to calculate its position. When the user hits Escape, useEscapeKey sets node.open.value = false.
None of these composables need to know about each other. They only talk to the node.
Where to go next
- Positioning: How
usePositionuses the node to compute coordinates. - Interaction model: How triggers and dismissal composables drive
node.open. useFloatingNodeAPI: Full options and return types.