Core Concepts

Interaction model

How VFloat opens, closes, and coordinates floating surfaces.

Interaction composables answer one question: when does this surface open and close?

They do not calculate coordinates or touch styles. Instead, they listen to events on the node elements and read or update node.open.

Triggers and dismissals

Rather than packing interaction modes into a single configuration object, VFloat splits them into focused composables:

Because node.open is a standard Vue ref, every composable simply mutates node.open.value.

Combining behaviors

Real-world surfaces often require multiple interaction rules at once.

For example, an accessible tooltip needs hover for mouse users, focus for keyboard users, and Escape key dismissal so keyboard users can hide the tooltip without moving focus:

<script setup lang="ts">
import { ref } from "vue";
import { useEscapeKey, useFloatingNode, useFocus, useHover, usePosition, useRole } from "v-float";

const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);

const node = useFloatingNode({ anchorEl, floatingEl });

usePosition(node, { placement: "top" });

// Multiple inputs driving the same open state
useHover(node);
useFocus(node);
useEscapeKey(node);
useRole(node, { role: "tooltip" });
</script>

These composables do not conflict because they only act on node.open. Hovering opens the surface, hitting Escape closes it, and tabbing away closes it on blur.

Awareness of nested surfaces

Dismissal composables are aware of the node hierarchy.

When you nest a submenu inside a parent menu, useOutsideClick checks node.contains(event.target). Because node.contains walks open child nodes, clicking an item in the submenu does not accidentally dismiss the parent.

Similarly, useEscapeKey closes the topmost open child first instead of closing the entire menu tree at once.

Where to go next

  • Hierarchy: How nested surfaces coordinate dismissal and focus.
  • Floating node: Learn how the shared hub manages element refs and open state.
  • Focus models: Focus placement and containment strategies.
  • Hover & dismissal: Safe corridors and Escape key coordination.

Released under the MIT License. Copyright © 2026