focus-trap-lite

Lightweight (≤2kB) focus trapping utility for implementing accessible keyboard navigation constraints in modal dialogs, sidebars, and other contained UI components.

Features

• ✅ Full WAI-ARIA compliance for accessibility
• ✅ Tiny footprint (ES6 module)
• ✅ Zero dependencies
• ✅ Flexible focus control
• ✅ Automatic cleanup
• ✅ TypeScript support

Installation

npm install focus-trap-lite

Usage

Basic Implementation

import { initFocusTrap } from 'focus-trap-lite'

// Initialize trap on modal open
function openModal() {
  const trap = initFocusTrap(modalElement)

  // Add your modal opening logic

  // Clean up manually if needed
  // trap.destroy()
}

// Trap automatically cleans up when:
// - User closes modal (Escape key)
// - Focus escapes trap boundaries (if logic allows)
// - Component unmounts

Advanced Configuration

// Container element with custom selector and options
initFocusTrap(document.querySelector('#modal-container'), '.custom-focusable', {
  focus: true, // Auto-focus on initialization
  firstFocusableElement: '#first-input', // Specific start element
})

// Nested Modals support
// The library maintains a stack of active traps.
// When a new trap is initialized, it takes precedence.
// When destroyed (e.g. via Escape), focus control returns to the previous trap.

API

initFocusTrap(element?, selector?, options?)

Parameter	Type	Description
element	Element	(Optional) DOM element to scope the focus trap. When omitted, uses document.body
selector	string	(Optional) CSS selector for focusable elements within container. Default: standard focusable elements
options	Object	(Optional) Configuration object
options.focus	boolean	Auto-focus the first element on initialization. Default: false
options.firstFocusableElement	HTMLElement|string	Element to focus initially. Can be a selector string or DOM element.

Returns:

{
  destroy: () => void,     // Manually destroy the trap
  container: HTMLElement   // The container element
}

Behavior:

• Creates keyboard navigation constraints (Tab / Shift+Tab)
• Handles boundary focus wrapping
• Nested Traps: Supports multiple stacked traps (LIFO)
• Auto Cleanup:
  • On Escape key press
  • When calling destroy()
  • When calling function returns (if implicit, though manual destroy is recommended for SPAs)
• Smart Filtering: Ignores hidden, invisible, or tabindex="-1" elements

Changelog

v0.1.0

• Breaking Change: initFocusTrap now returns an object { destroy, container } instead of void.
• New Feature: Added options parameter.
  • options.focus: Auto-focus support.
  • options.firstFocusableElement: Custom initial focus target.
• New Feature: Nested focus traps support (Stack-based).
• New Feature: Escape key support for closing the trap.
• Improvement: Better filtering of non-focusable elements (hidden, zero-size, tabindex="-1").
• Improvement: Optimized internal logic and variable naming.

Browser Support

Modern browsers with ES6 support:

Chrome	Firefox	Safari
88+	78+	14.1+

For legacy browser support, add Array.prototype.at() polyfill.

Contributing

1. Fork the repository
2. Clone your fork

git clone https://github.com/your-username/focus-trap-lite.git

3. Install dependencies

npm install

4. Create feature branch

git checkout -b feature/your-feature

5. Commit changes
6. Push to branch
7. Create Pull Request

License

MIT © Pipecraft

---

📝 Report issues on GitHub

>_