# useFocusTrap API

> Auto-generated API reference for `useFocusTrap` from @vuetify/v0 (Vuetify0).
> Source of truth: https://0.vuetifyjs.com/api/use-focus-trap

## Related

- https://0.vuetifyjs.com/composables/system/use-focus-trap
- https://0.vuetifyjs.com/components/disclosure/dialog
- https://0.vuetifyjs.com/composables/system/use-click-outside
- https://0.vuetifyjs.com/composables/system/use-event-listener
- https://0.vuetifyjs.com/composables/system/use-roving-focus
- https://0.vuetifyjs.com/composables/plugins/use-stack

## Functions

### useFocusTrap

Confines Tab / Shift+Tab to the subtree of `target`.

```ts
(target: MaybeElementRef, options?: UseFocusTrapOptions) => UseFocusTrapReturn
```

### tabbable

```ts
typeof tabbable
```

## Options

| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| `active` | `MaybeRefOrGetter<boolean> \| undefined` | — | no | Reactive activation source. When it flips true the trap engages and focuses into the root; when it flips false the trap releases and restores focus.  Omit it entirely to drive the trap imperatively. |
| `initial` | `false \| { readonly value: HTMLElement \| Element \| SVGElement \| import("/home/runner/work/0/0/node_modules/.pnpm/vue@3.5.42_typescript@6.0.3/node_modules/vue/dist/vue").ComponentPublicInstance \| null \| undefined; } \| (() => HTMLElement \| Element \| SVGElement \| import("/home/runner/work/0/0/node_modules/.pnpm/vue@3.5.42_typescript@6.0.3/node_modules/vue/dist/vue").ComponentPublicInstance \| null \| undefined) \| HTMLElement \| Element \| SVGElement \| import("/home/runner/work/0/0/node_modules/.pnpm/vue@3.5.42_typescript@6.0.3/node_modules/vue/dist/vue").ComponentPublicInstance \| undefined` | — | no | Where focus lands when the trap engages.  - omitted — the first tabbable descendant, falling back to the root - `false` — nothing is focused; the first Tab pulls focus in instead - an element / ref / getter — that node is focused directly. If it cannot   take focus, the first tabbable descendant (or the root) is used instead |
| `restore` | `boolean \| undefined` | `true` | no | Return focus to the element that was focused before activation.  Skipped when focus already sits on an outside control by the time the trap releases — closing a dialog must not steal focus back from whatever the user just clicked. A blur to `<body>` still restores. |
| `listen` | `boolean \| undefined` | `true` | no | Bind the capture-phase `keydown` listener on `document`.  Set `false` when a consumer-owned listener will call {@link UseFocusTrapReturn.onKeydown} itself — otherwise the document listener has already wrapped by the time a root handler runs. A `listen: false` trap is not pushed onto the nest stack. |
| `onEscape` | `((event: KeyboardEvent) => void) \| undefined` | — | no | Invoked on Escape while this trap is the last *connected* trap that has `onEscape` and owns focus.  Opt-in and side-effect free: the trap never calls `preventDefault()` and never deactivates itself. An inner Tab-only trap (no `onEscape`) does not eat Escape — it falls through to the next connected trap that has a handler. Gate on a `useStack` ticket when dismissal policy is overlay-stack, not trap-stack. |

## Methods

| Name | Type | Description |
|---|---|---|
| `activate` | `() => void` | Engage the trap: capture the focused element for a later restore, bind containment, and focus into the root once it exists. No-op when already engaged, so it never overwrites the captured restore target. |
| `deactivate` | `() => void` | Release the trap and restore focus. No-op when not engaged. |
| `onKeydown` | `(event: KeyboardEvent) => void` | The keydown handler. Bound on `document` in the capture phase while the trap is engaged unless {@link UseFocusTrapOptions.listen} is `false`. |

## Properties

| Name | Type | Description |
|---|---|---|
| `isActive` | `Readonly<Ref<boolean, boolean>>` | Whether the trap is currently engaged |