Focus Scope

Manages focus within a component boundary with support for trapping and looping focus navigation.

Focus Scope provides enhanced control over keyboard focus management within component boundaries. It can trap focus within its container and optionally loop focus navigation, making it ideal for modal interfaces and other interactive components that need to manage focus states.

API Reference

Prop	Default	Type
`as`	`"div"`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`loop`	`false`	`boolean` When `true`, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tababble.
`present`	`true`	`boolean` Whether the scope is currently visible. Lets a consumer keep the scope mounted but hidden (e.g. `display: none`) and still get correct auto-focus: the mount auto-focus is skipped while not present, and re-runs when it becomes present again. Defaults to `true` so consumers that mount the scope only while visible are unaffected.
`trapped`	`false`	`boolean` When `true`, focus cannot escape the focus scope via keyboard, pointer, or a programmatic focus.

Event	Payload
`mountAutoFocus`	`event: Event` Event handler called when auto-focusing on mount. Can be prevented.
`unmountAutoFocus`	`event: Event` Event handler called when auto-focusing on unmount. Can be prevented.

FocusScope.vue source

Example

Basic usage with focus trapping

<template>
  <FocusScope :trapped="true">
    <div>
      <button>Action 1</button>
      <button>Action 2</button>
      <button>Close</button>
    </div>
  </FocusScope>
</template>

With Focus Looping

Enable both trapping and looping for complete focus management:

<template>
  <FocusScope :trapped="true" :loop="true">
    <div>
      <button v-for="item in items" :key="item.id">
        {{ item.label }}
      </button>
    </div>
  </FocusScope>
</template>

Handling Focus Event

<script setup>
function handleMountFocus(event) {
  // Prevent default auto-focus behavior if needed
  event.preventDefault()
}
</script>

<template>
  <FocusScope
    @mount-auto-focus="handleMountFocus"
    @unmount-auto-focus="handleUnmountFocus"
  >
    <div>
      …
    </div>
  </FocusScope>
</template>

When using trapped mode, ensure there is always at least one focusable element within the scope to prevent focus from being trapped in an inaccessible state.

Config Provider

Wraps your app to provide global configurations.

Presence

Manages mounting and unmounting of element with transition support.