Focus Models
Focus management determines how keyboard users and assistive technologies navigate into, through, and out of floating surfaces.
When focus handling is omitted, floating elements create severe accessibility obstacles: keyboard users become trapped in invisible loops, screen readers announce content out of order, or closing a dialog dumps focus at the top of the <body> element.
Every floating interface in VFloat operates under one of two core focus models: companion surfaces or destination surfaces.
Companion surfaces vs destination surfaces
The first step in designing an accessible floating surface is deciding where DOM focus should live while the surface is open:
- Companion surfaces (Focus stays on the anchor): The floating element acts as a contextual companion. Focus never leaves the trigger element or input field. This is the model for tooltips (WAI-ARIA APG Tooltip Pattern), hover cards, and search inputs with virtual suggestion lists.
- Destination surfaces (Focus moves into the surface): The floating element becomes the user's primary workspace. Focus moves inside upon opening and returns to the trigger when dismissed. This is the model for menus, popovers with interactive controls, and modal dialogs (WAI-ARIA APG Dialog (Modal) Pattern).
Companion surfaces: keeping focus on the trigger
For lightweight contextual overlays, moving focus into the surface would disrupt the user's workflow.
useFocus opens and closes floating surfaces based on the focus state of the anchor element.
Here is a companion tooltip that opens when the trigger gains keyboard focus:
<script setup lang="ts">
import { ref } from "vue";
import { useEscapeKey, useFloatingNode, useFocus, 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 } });
// Open on keyboard focus, dismiss on Escape or blur
useFocus(node);
useEscapeKey(node);
</script>
<template>
<button ref="anchorEl" type="button" aria-describedby="tip">Copy token</button>
<div v-if="node.open.value" id="tip" ref="floatingEl" role="tooltip">
Copies API token to clipboard
</div>
</template>
Keyboard-first focus detection
By default, useFocus enables requireFocusVisible: true.
This means the surface opens only when the anchor receives focus through keyboard navigation, matching the CSS :focus-visible pseudo-class. When a user clicks the anchor with a mouse or pointer device, the focus event is ignored. This prevents unwanted popups from flashing when clicking standard buttons.
Tab switch and window blur safety
When a user opens a companion surface and switches browser tabs or OS windows, the window fires a global blur event. When returning, the browser re-dispatches a focus event to the active element.
useFocus tracks window state internally to prevent ghost re-openings, ensuring a dismissed surface does not reopen unexpectedly simply because the user switched back to the application.
Destination surfaces: managing the focus lifecycle
When a floating element contains interactive controls, forms, or navigation items, it must manage the full four-phase focus lifecycle according to WCAG 2.1 SC 2.4.3 (Focus Order):
- Initial focus: Move focus into the surface immediately upon opening.
- Containment: Keep Tab navigation contained within the surface while active (WCAG 2.1 SC 2.1.2: No Keyboard Trap).
- Background isolation: Prevent screen readers and keyboard users from discovering content behind the surface.
- Return focus: Restore focus cleanly to the trigger button when dismissed.
useFocusTrap coordinates all four phases through a single composable.
Here is a modal dialog with full focus orchestration:
<script setup lang="ts">
import { ref } from "vue";
import {
useClick,
useEscapeKey,
useFloatingNode,
useFocusTrap,
useOutsideClick,
useRole,
} from "v-float";
const anchorEl = ref<HTMLElement | null>(null);
const floatingEl = ref<HTMLElement | null>(null);
const node = useFloatingNode({ anchorEl, floatingEl });
useClick(node);
useOutsideClick(node);
useEscapeKey(node);
// Orchestrate initial focus, Tab wrapping, inert isolation, and return focus
useFocusTrap(node, {
modal: true,
returnFocus: true,
});
useRole(node, { role: "dialog", modal: true });
</script>
<template>
<button ref="anchorEl" type="button">Open Settings</button>
<div v-if="node.open.value" ref="floatingEl" class="dialog">
<h2>Settings</h2>
<input type="text" placeholder="Workspace name" />
<button type="button" @click="node.open.value = false">Save</button>
</div>
</template>
1. Initial focus placement
When node.open.value becomes true, useFocusTrap scans the floating element for tabbable children.
By default, it focuses the first tabbable element inside the container. If no tabbable elements exist, it applies tabindex="-1" to the floating container itself and focuses the container. This ensures screen readers immediately announce the dialog's accessible title.
2. Focus containment and Tab wrapping
When modal: true is configured, useFocusTrap listens for document-level Tab key events:
- Pressing Tab on the last interactive element wraps focus back to the first interactive element.
- Pressing Shift+Tab on the first interactive element wraps focus to the last interactive element.
Because the trap operates at the document level, it catches focus even if the user attempts to tab into the browser address bar or body, keeping focus strictly contained.
3. Background isolation with HTML inert
Trapping Tab is not enough on its own. Sighted screen reader users and virtual cursor users can still navigate outside the dialog if the surrounding DOM remains accessible.
When modal: true is enabled, useFocusTrap applies the native HTML inert attribute to all outside DOM siblings. While inert is active:
- Outside elements cannot receive focus programmatically or through user interaction.
- Screen readers ignore all outside DOM nodes as if they do not exist.
- Pointer clicks outside the surface are blocked.
When the surface closes, inert is removed and the original page interactivity is restored.
4. Return focus restoration
When the surface closes (via Escape, an outside click, or an action button), focus must return to the element that originally launched it.
useFocusTrap records the trigger element upon activation and restores focus upon deactivation. It enables preventScroll: true by default, preventing unexpected viewport jumps when returning focus to an off-screen trigger.
Modal vs non-modal surfaces
Not all destination surfaces should isolate the page:
- Modal surfaces (
modal: true): For dialogs, alerts, and confirmation sheets. Traps Tab, isolates the background withinert, and prevents outside scrolling. - Non-modal surfaces (
modal: false): For dropdown menus and command palettes. Focus enters the surface upon opening, but the background remains interactive. Users can press Tab to leave the surface, which triggers dismissal when paired withcloseOnFocusOut: true.
Nested floating families
When a dialog opens a dropdown menu or date picker, two floating surfaces are active simultaneously.
Because FloatingNode tracks parent-child hierarchy, useFocusTrap coordinates nested surfaces automatically. When the child dropdown opens, the parent dialog's trap recognizes that focus remains inside its floating family via node.contains(). The parent trap does not steal focus back from the child.
Official specifications
- WAI-ARIA APG Dialog (Modal) Pattern: Expected keyboard interaction and focus containment for modal dialogs.
- WHATWG HTML Specification: The
inertattribute: Official standard for background element inertness and accessibility tree omission. - W3C WCAG 2.1 SC 2.4.3: Focus Order: Ensuring focusable components receive focus in an order that preserves meaning and operability.
Where to go next
- Keyboard Navigation: Implement roving tabindex and virtual focus for menus and listboxes.
- Hover & Dismissal: Learn how to meet WCAG 2.1 SC 1.4.13 for hover and Escape key dismissal.
useFocusTrapAPI: Complete options and configuration parameters.