Vue Focus Trap Component

Common errors

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

  cause 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.

  cause 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

  cause 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'.

  cause 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`).

Warnings

• breaking Version 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.
• gotcha The `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.
• gotcha The `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.
• gotcha When 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"`.
• gotcha Different 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`).

Install

• npm install focus-trap-vue npm
• yarn add focus-trap-vue yarn
• pnpm add focus-trap-vue pnpm

Imports

• FocusTrap
  wrong:

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

  correct:

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

  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`.

Quickstart

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');