Core Concepts

Floating node

A shared context for VFloat composables.

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 optional arrowEl.
  • Open state: a reactive open boolean 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) and useClick(node) toggle node.open.
  • useEscapeKey(node) and useOutsideClick(node) close node.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

Released under the MIT License. Copyright © 2026