useFocusTrap

A composable that confines keyboard focus to a root element for as long as the trap is active.

Usage

A native <dialog> opened with showModal() is trapped by the browser, so it needs nothing here. Modal overlays that are not a native dialog do: a Dialog.Content rendered as="div", a drawer, a command palette. Tooltips and menus typically do not. useFocusTrap wraps Tab and Shift+Tab at the first and last tabbable descendant, focuses into the root on activate, and returns focus to the previously focused element on deactivate, unless focus already left the root.

<script setup lang="ts">
  import { useFocusTrap } from '@vuetify/v0'
  import { shallowRef, useTemplateRef } from 'vue'

  const isOpen = shallowRef(false)
  const panel = useTemplateRef<HTMLElement>('panel')

  useFocusTrap(panel, { active: isOpen })
</script>

<template>
  <button @click="isOpen = true">Open</button>

  <div v-if="isOpen" ref="panel" tabindex="-1" aria-label="Trapped panel">
    <input>
    <button @click="isOpen = false">Close</button>
  </div>
</template>

Architecture

useFocusTrap composes useDocumentEventListener and useToggleScope. Each engaged listen: true trap binds its own document-level listener; a module-level stack chooses which of those listeners owns Tab and Escape:

The keydown listener is bound to document in the capture phase, not to the root. A root-bound listener stops firing the moment focus leaves the subtree — a backdrop click that blurs to <body>, or a stray programmatic focus() — and the trap is then dead with no way back. Binding at the document means an escaped focus is recovered on the next Tab, and containment survives an inner stopPropagation().

Only the boundaries are intercepted. A Tab press in the middle of the list passes through untouched, so a nested widget keeps full control of its own Tab handling everywhere except the first and last stop.

Options

import { useFocusTrap } from '@vuetify/v0'
import { shallowRef, useTemplateRef } from 'vue'

const isOpen = shallowRef(false)
const panel = useTemplateRef<HTMLElement>('panel')
const cancel = useTemplateRef<HTMLElement>('cancel')

// Destructive dialogs should land on the safe action
useFocusTrap(panel, { active: isOpen, initial: cancel })

Reactivity

Examples

Recipes

Escape Only for the Top Overlay

Nested traps already resolve to the last connected trap that has onEscape. Nested overlays still need a stacking guard when dismissal policy is overlay-stack, not trap-stack — useStack tracks which overlay is topmost:

import { useFocusTrap, useStack } from '@vuetify/v0'
import { shallowRef, useTemplateRef } from 'vue'

const isOpen = shallowRef(false)
const panel = useTemplateRef<HTMLElement>('panel')
const stack = useStack()
const ticket = stack.register({ onDismiss: () => (isOpen.value = false) })

useFocusTrap(panel, {
  active: isOpen,
  onEscape: event => {
    if (!ticket.globalTop.value) return
    event.preventDefault()
    isOpen.value = false
  },
})

Releasing Tab to an Inner Widget

A code editor or grid inside the trap needs Tab for itself. Because only the boundaries are intercepted, this works without configuration — Tab presses between the first and last stop are never touched.

A widget that sits at a boundary cannot opt out, though. The trap listens on document in the capture phase, so it has already wrapped focus by the time a handler inside the root runs; that handler’s preventDefault() comes too late. Two ways out:

• Keep the widget off the boundary. A tabbable element after it — a footer button, or a tabindex="0" sentinel — makes the widget interior, and its Tab handling is then untouched.

• Own the listener. Pass listen: false and call onKeydown yourself — otherwise the document capture listener has already wrapped.

import { useFocusTrap } from '@vuetify/v0'
import { shallowRef, useTemplateRef } from 'vue'

const isOpen = shallowRef(false)
const panel = useTemplateRef<HTMLElement>('panel')
const editorHasFocus = shallowRef(false)
const trap = useFocusTrap(panel, { active: isOpen, listen: false })

function onPanelKeydown (event: KeyboardEvent) {
  if (editorHasFocus.value && event.key === 'Tab') return

  trap.onKeydown(event)
}

Accessibility

A focus trap is one half of a modal contract. The trap manages focus order; you still supply the rest:

aria-disabled="true" controls are treated as tabbable, per APG↗︎: an aria-disabled control stays in the tab order, and skipping it would let the browser walk past the computed boundary and out of the trap. This is a deliberate divergence from roving-focus composables like useRovingFocus, which must skip disabled items.

The boundary is computed the way the browser computes tab order, so a radio group counts as one stop — the checked radio if it is otherwise tabbable, otherwise the first otherwise-tabbable member. Disabled, hidden, or inert members are not stops and do not hide the rest of the group. Grouping follows the HTML rule of same name plus same form owner, so two forms on a page keep independent groups.

Positive tabindex values are the one case the trap declines to model: candidates are collected in document order and never re-sorted into their real tab position, so a root containing them can leak at the boundary. Use 0 and -1 only.

FAQ