Registry / web-framework / focus-trap-vue

focus-trap-vue

library4.1.0jsnpmunverified

focus-trap-vue is a Vue component designed to enhance web accessibility by programmatically trapping keyboard focus within a specified DOM element. This is crucial for UI patterns like modals, dialogs, and sidebars, preventing users of assistive technologies from accidentally tabbing out of the active context. The current stable version is 4.1.0, last published in August 2025, with regular patch and minor releases, indicating active maintenance and a stable API. It acts as a Vue-specific wrapper around the robust `focus-trap` library, inheriting its extensive focus management capabilities. Key differentiators include its seamless integration into Vue applications, support for both Vue 2 (via `@legacy` package) and Vue 3, and flexible control mechanisms via `active` prop, `v-model:active`, or direct method calls, while enforcing best practices for accessibility by leveraging its underlying peer dependency.

web-framework auth-security

npm install focus-trap-vue

github ↗package ↗

INSTALL

IMPORT

SIG · FOCUS-TRAP-VUE

focus-trap-vue

web-frameworkjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FocusTrap

✓ import { FocusTrap } from 'focus-trap-vue';

✗ const FocusTrap = require('focus-trap-vue').FocusTrap;

This is the primary named export for the component. CommonJS `require` is generally incorrect in modern Vue 3 ESM projects.

FocusTrapTabbableOptions

✓ import type { FocusTrapTabbableOptions } from 'focus-trap-vue';

Import types explicitly for type-checking when using TypeScript, particularly for advanced prop configurations like `tabbableOptions`.

Demonstrates a basic focus trap using `v-model:active` to control visibility and setting `initialFocus` to an input field within a modal-like cookie consent dialog for improved accessibility.

import { createApp, ref } from 'vue'; import { FocusTrap } from 'focus-trap-vue'; const app = createApp({ components: { FocusTrap, }, setup() { const isActive = ref(false); const nameInput = ref<HTMLInputElement | null>(null); return { isActive, nameInput, acceptCookies: () => { alert('Cookies accepted!'); isActive.value = false; }, }; }, template: ` <div> <button @click="isActive = true">Open Cookie Consent</button> <focus-trap v-model:active="isActive" :initial-focus="() => nameInput.value"> <div v-if="isActive" style="border: 1px solid #ccc; padding: 20px; background: #f9f9f9; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 1000; width: 300px; text-align: center;"> <p>Do you accept our use of cookies?</p> <label>Your Name: <input ref="nameInput" type="text" /></label> <div style="margin-top: 15px;"> <button @click="acceptCookies" style="margin-right: 10px;">Yes, I accept</button> <button @click="isActive = false">No, thank you</button> </div> </div> </focus-trap> <p style="margin-top: 200px;">Content behind the modal.</p> <button>Another button</button> </div> `, }); app.mount('#app');

Debug

Known issues

breakingVersion 4.0.0 introduced breaking changes, primarily due to upgrading its underlying `focus-trap` dependency to v7. This includes dropping support for Internet Explorer browsers and other behavioral changes in the core focus trapping logic. Refer to the `focus-trap` changelog for full details.

fix

Review the `CHANGELOG.md` for `focus-trap-vue` and `focus-trap` to understand necessary code adaptations, especially if migrating from pre-4.0.0 versions or if IE support is critical. Ensure `focus-trap` v7 is installed.

affects: >=4.0.0

gotchaThe `focus-trap` and `vue` packages are peer dependencies and must be installed separately alongside `focus-trap-vue`. Failure to do so will result in runtime errors.

fix

Ensure `npm install focus-trap vue` (for Vue 3) or `npm install focus-trap vue@^2 focus-trap-vue@legacy` (for Vue 2) is run.

affects: >=3.0.0

gotchaThe `FocusTrap` component is designed to wrap exactly one child element. Providing multiple root children will lead to undefined behavior or errors.

fix

Ensure the `FocusTrap` component directly contains only a single HTML element or Vue component as its immediate child.

affects: >=3.0.0

gotchaWhen setting `initialFocus`, the target element should be a focusable and ideally interactable element (e.g., an input, button, or an element with `tabindex="-1"` if it's a container). If a non-focusable element is targeted, the trap might not behave as expected.

fix

Always provide a valid CSS selector or a function returning a focusable DOM `Element` for the `initialFocus` prop. If targeting a container, ensure it has `tabindex="-1"`.

affects: >=3.0.0

gotchaDifferent versions of `focus-trap-vue` are required for Vue 2 vs. Vue 3. The main package (`focus-trap-vue`) is for Vue 3, while Vue 2 requires `focus-trap-vue@legacy`.

fix

For Vue 2 projects, install `focus-trap-vue@legacy`. For Vue 3 projects, install `focus-trap-vue` (without `@legacy`).

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'focus-trap-vue' or 'Cannot find name 'FocusTrap'.

The package or its types were not installed correctly, or the import path is wrong.

fix

Verify installation with `npm install focus-trap-vue` (or `@legacy`) and ensure correct import statement: `import { FocusTrap } from 'focus-trap-vue';`.

The FocusTrap component expects a single child element.

The `FocusTrap` component has more than one root child element in its slot.

fix

Wrap all content within the `FocusTrap` component inside a single container `<div>` or custom component.

[Vue warn]: Failed to resolve component: FocusTrap

The `FocusTrap` component was used in a template but not properly registered with Vue.

fix

Ensure `FocusTrap` is either imported and registered locally in a component's `components` option, or globally registered via `app.component('FocusTrap', FocusTrap)` for Vue 3.

Vue packages version mismatch: - focus-trap-vue requires Vue '^3.0.0' but Vue version is '2.x.x'.

An incorrect version of `focus-trap-vue` was installed for the corresponding Vue version in the project.

fix

For Vue 2 projects, use `npm install focus-trap-vue@legacy`. For Vue 3 projects, ensure `focus-trap-vue` is installed without `@legacy` and that your `vue` version meets the peer dependency requirement (e.g., `^3.0.0`).

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

focus-traprequiredProvides the core focus trapping logic; required as a peer dependency.

vuerequiredThe foundational Vue.js framework, required for the component to function.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/posva/focus-trap-vue ↗

packagehttps://www.npmjs.com/package/focus-trap-vue ↗