First Tooltip
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);
anchorElreferences the trigger element (the button).floatingElreferences 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 theoffsetmiddleware.
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"andref="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:
- Initial state: The button renders on screen. Because
node.open.valueisfalse, the tooltip is not rendered. - Pointer enters: The user hovers over the button.
useHoversetsnode.open.value = true. - Tooltip mounts: Vue renders the tooltip
<div>and assigns the DOM node tofloatingEl. - Position calculation:
usePositionmeasures both elements, applies the 8-pixel offset, and updatesfloatingElstyles to sit centered above the button. - Pointer leaves: The user moves the pointer away.
useHoversetsnode.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
useFloatingNodefor the complete node API.