Getting Started

First Tooltip

Build a hover-triggered tooltip positioned above an anchor button with offset spacing.

In this tutorial, you will build a tooltip that appears above a button on hover, stays centered, and keeps an 8-pixel gap from the trigger.

The complete example

Here is the complete working component:

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

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

const node = useFloatingNode({ anchorEl, floatingEl });
usePosition(node, {
  placement: "top",
  middlewares: {
    offset: 8,
  },
});

useHover(node);
</script>

<template>
  <button ref="anchorEl" type="button">Save changes</button>

  <div v-if="node.open.value" ref="floatingEl" role="tooltip">This button saves your changes.</div>
</template>

Set up element refs

Start by declaring template refs for the two elements:

const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
  • anchorEl references the trigger element (the button).
  • floatingEl references the floating element (the tooltip).

VFloat uses these refs to measure element dimensions and attach DOM event listeners.

Create the floating node

Pass the element refs into useFloatingNode to create the node:

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

The returned node acts as the shared state hub:

  • node.refs: Exposes the element references to other composables.
  • node.open: A reactive boolean ref tracking whether the tooltip is visible.

All VFloat positioning and interaction composables connect to this node.

Position above the button

Pass the node to usePosition to position the tooltip:

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

This configuration sets up the layout:

  • placement: "top" centers the tooltip above the button.
  • middlewares: { offset: 8 } adds an 8-pixel gap between the button and the tooltip using the offset middleware.

usePosition computes coordinates and applies transform styles directly to floatingEl. You do not need to bind :style in your template.

Toggle visibility on hover

Pass the node to useHover to handle mouse hover:

useHover(node);

useHover listens for pointer events on the anchor button:

  • When the pointer enters the button, it sets node.open.value = true.
  • When the pointer leaves the button, it sets node.open.value = false.

Event listeners and cleanup are handled automatically when the component unmounts.

Bind elements in the template

Connect your template refs and conditionally render the tooltip:

<button ref="anchorEl" type="button">
  Save changes
</button>

<div v-if="node.open.value" ref="floatingEl" role="tooltip">
  This button saves your changes.
</div>
  • ref="anchorEl" and ref="floatingEl" bind the DOM elements to your refs.
  • v-if="node.open.value" renders the tooltip only when it is open.
  • role="tooltip" adds the semantic role for screen readers.

Because VFloat is headless, you have full control over HTML markup, CSS classes, and styles.

What happens at runtime

Here is the lifecycle of the tooltip in action:

  1. Initial state: The button renders on screen. Because node.open.value is false, the tooltip is not rendered.
  2. Pointer enters: The user hovers over the button. useHover sets node.open.value = true.
  3. Tooltip mounts: Vue renders the tooltip <div> and assigns the DOM node to floatingEl.
  4. Position calculation: usePosition measures both elements, applies the 8-pixel offset, and updates floatingEl styles to sit centered above the button.
  5. Pointer leaves: The user moves the pointer away. useHover sets node.open.value = false, and Vue unmounts the tooltip.

Where to go next

  • Keyboard and screen reader accessibility: Read ARIA & Semantics and Hover & Dismissal to add accessible labeling, Escape dismissal, and safe polygon pointer paths.
  • Keyboard-navigated menus: Read First Menu to see how click triggers, outside dismissal, and roving focus combine into a dropdown menu.
  • Collision handling: Read Middlewares to prevent floating surfaces from overflowing the viewport.
  • Node reference: Inspect useFloatingNode for the complete node API.

Released under the MIT License. Copyright © 2026