focus-trap-tiny

A lightweight, zero-dependency focus trap for modals and dialogs.
Uses native browser APIs — no polyfills, no bloat.

▶ Live Demo

Why?

Existing solutions like focus-trap are powerful but pull in dependencies and polyfills you probably don't need anymore. focus-trap-tiny does one thing well: traps keyboard focus inside a container using only what the browser already gives you.

• < 1 KB minified + gzipped
• Zero dependencies
• Works with any framework or vanilla JS
• Handles Shift+Tab, inert, hidden elements, and dynamic content
• Catches focus that escapes via mouse click or programmatic focus(), not just Tab
• Configurable initial / return focus, with a fallback for empty dialogs
• Returns focus on deactivation (great for modals)

Install

npm install focus-trap-tiny

Usage

import createFocusTrap from 'focus-trap-tiny';

const modal = document.getElementById('my-modal');
const trap = createFocusTrap(modal, {
  onEscape: () => closeModal(),
});

// When modal opens
trap.activate();

// When modal closes
trap.deactivate();

API

createFocusTrap(container, options?)

| Parameter | Type | Description | |-------------|---------------|--------------------------------------| | container | HTMLElement | The element to trap focus within. | | options | Object | Optional configuration (see below). |

Options

| Option | Type | Default | Description | |-----------------|-------------------------------|---------|-----------------------------------------------------------------------------| | initialFocus | boolean \| FocusTarget | true | Where to send focus on activate(). true = first focusable, false = none, or a target. | | returnFocus | boolean \| FocusTarget | true | Where to send focus on deactivate(). true = previously focused element, false = none, or a target. | | fallbackFocus | FocusTarget | null | Element to focus when the container has no focusable children. Defaults to the container itself. | | onEscape | Function | null | Callback fired when the Escape key is pressed. |

A FocusTarget is a CSS selector string, an HTMLElement, or a function returning an element. For initialFocus/fallbackFocus, selectors resolve within the container; for returnFocus, they resolve against the whole document (since the return target is usually the trigger outside the modal).

createFocusTrap(modal, {
  initialFocus: '#email',      // focus a specific field on open
  returnFocus: triggerButton,  // restore focus to the button that opened it
});

Returns

| Method | Description | |--------------|-----------------------------------------------------------| | activate() | Starts the focus trap. | | deactivate() | Stops the trap and optionally restores previous focus. | | update() | Re-scans focusable elements (call after DOM changes). |

What counts as "focusable"?

• <a href>
• <button> (not disabled)
• <input>, <select>, <textarea> (not disabled)
• Elements with tabindex ≥ 0
• <details> > <summary>
• <audio controls>, <video controls>

Elements that are display: none, visibility: hidden, or inside an [inert] container are automatically excluded. If the container has no focusable children, focus falls back to the container itself (or your fallbackFocus target) so focus is never lost.

Framework Examples

React

import { useEffect, useRef } from 'react';
import createFocusTrap from 'focus-trap-tiny';

function Modal({ isOpen, onClose, children }) {
  const ref = useRef(null);

  useEffect(() => {
    if (!isOpen || !ref.current) return;
    const trap = createFocusTrap(ref.current, { onEscape: onClose });
    trap.activate();
    return () => trap.deactivate();
  }, [isOpen, onClose]);

  if (!isOpen) return null;
  return <div ref={ref} role="dialog" aria-modal="true">{children}</div>;
}

Vue

<script setup>
import { ref, watch } from 'vue';
import createFocusTrap from 'focus-trap-tiny';

const props = defineProps(['isOpen']);
const emit = defineEmits(['close']);
const dialogRef = ref(null);

watch(() => props.isOpen, (open) => {
  if (open && dialogRef.value) {
    const trap = createFocusTrap(dialogRef.value, { onEscape: () => emit('close') });
    trap.activate();
  }
});
</script>

License

MIT