Accessible Focus Trapping

Common errors

• TypeError: Cannot read properties of undefined (reading 'activate')

  cause `createFocusTrap` was called with a non-existent or null DOM element, resulting in `undefined` being returned. Subsequently, `undefined.activate()` throws an error.
  fix Ensure the DOM element passed to `createFocusTrap` exists and is a valid `HTMLElement`. Check for `null` or `undefined` returns from `document.getElementById` or `document.querySelector`.

• Focus trap is not working as expected (e.g., focus escapes the modal, tabbing order is incorrect, clicks outside are not blocked).

  cause This is often due to the Safari 'Press Tab to highlight each item on a webpage' setting being disabled, or incorrectly configured `initialFocus` options, or elements within the trap not being correctly identified as tabbable by `tabbable`.
  fix For Safari, ensure the specific setting is enabled. Verify that your elements are natively tabbable or correctly marked with `tabindex`. Review the `tabbable` library documentation for details on what elements are considered tabbable. Also, check for CSS properties like `display: none` or `visibility: hidden` on the trap's container or its tabbable children.

• ReferenceError: FocusTrap is not defined

  cause Occurs when using the UMD build (e.g., from unpkg) but trying to access `FocusTrap` globally without it being loaded, or trying to destructure `createFocusTrap` when only `window.FocusTrap` is available.
  fix Ensure the UMD script for `focus-trap` is properly loaded. When loaded via UMD, the exports are typically available under `window.FocusTrap`, so you would access `window.FocusTrap.createFocusTrap`.

Warnings

• breaking The `onPostActivate()` callback now correctly executes *after* the initial focus node has received focus and the trap is fully activated. Previously, it would fire prematurely. This aligns the behavior with the intended purpose of `onPostActivate()`.
  Fix: Review existing `onPostActivate()` implementations. If you relied on the previous, incorrect timing, you may need to adjust your logic or use `onActivate()` if you need a callback before focus is set.
• gotcha In Safari, the default browser settings prevent tabbing through all elements on a webpage. This significantly impacts how `focus-trap` determines and cycles through tabbable elements, potentially causing traps to not work as expected.
  Fix: Users and developers must enable 'Preferences > Advanced > Press Tab to highlight each item on a webpage' in Safari settings for focus traps to function correctly.
• deprecated Support for Internet Explorer (all versions) has been officially dropped due to Microsoft's end-of-life for IE. The library no longer guarantees functionality or provides fixes for IE-specific issues.
  Fix: Avoid using `focus-trap` in projects requiring IE compatibility. Consider polyfills or alternative strategies for legacy browser support if absolutely necessary, but it's generally recommended to drop IE support.
• gotcha When using the UMD build (`dist/focus-trap.umd.js`) directly in the browser without a module bundler, the `tabbable` dependency is *not* bundled with `focus-trap`. It must be included separately and loaded *before* `focus-trap`.
  Fix: Ensure that `<script src="https://unpkg.com/tabbable/dist/index.umd.js"></script>` is placed in your HTML *before* `<script src="https://unpkg.com/focus-trap/dist/focus-trap.umd.js"></script>`.

Install

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

Imports

• createFocusTrap
  wrong:

  import createFocusTrap from 'focus-trap';

  correct:

  import { createFocusTrap } from 'focus-trap';

  This library uses named exports. There is no default export for the primary function.
• FocusTrap

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

  Import the type definition for the FocusTrap instance if working with TypeScript.
• createFocusTrap (CommonJS)
  wrong:

  const createFocusTrap = require('focus-trap');

  correct:

  const { createFocusTrap } = require('focus-trap');

  While CommonJS `require` works, the primary export is named. ESM imports are preferred in modern Node.js and bundled environments.
• createFocusTrap (UMD)

  <!-- Include tabbable first -->
  <script src="https://unpkg.com/tabbable/dist/index.umd.js"></script>
  <script src="https://unpkg.com/focus-trap/dist/focus-trap.umd.js"></script>
  <script>
    const { createFocusTrap } = window.FocusTrap;
  </script>

  When using the UMD build from unpkg, `tabbable` must be included separately and *before* focus-trap. The library exposes its named exports on `window.FocusTrap`.

Quickstart

Demonstrates creating, activating, and deactivating a focus trap for a modal dialog, including managing visibility and returning focus.

import { createFocusTrap } from 'focus-trap';

const modalElement = document.getElementById('my-modal');
const openButton = document.getElementById('open-modal-button');
const closeButton = document.getElementById('close-modal-button');

let focusTrapInstance: ReturnType<typeof createFocusTrap> | null = null;

function openModal() {
  if (modalElement) {
    modalElement.style.display = 'block';
    focusTrapInstance = createFocusTrap(modalElement, {
      onDeactivate: () => {
        if (modalElement) modalElement.style.display = 'none';
        openButton?.focus(); // Return focus to the element that opened the modal
      },
      initialFocus: closeButton || undefined, // Optionally focus the close button first
    });
    focusTrapInstance.activate();
  }
}

function closeModal() {
  if (focusTrapInstance) {
    focusTrapInstance.deactivate();
    focusTrapInstance = null;
  }
}

openButton?.addEventListener('click', openModal);
closeButton?.addEventListener('click', closeModal);

// Example: simulate opening a modal after a delay
setTimeout(openModal, 1000);