keys/hooks/use-focus-trap

useFocusTrap

standalonefocusaccessibility

Trap Tab/Shift+Tab focus within a container element. Auto-focuses first focusable element on mount, restores focus on unmount.

useFocusTrap keeps Tab and Shift+Tab focus inside a container while it is mounted — the standard requirement for modal dialogs. It is standalone (no provider), moves focus into the container on activation, recaptures focus if it escapes, and restores focus to the previously focused element when the trap releases. Nested traps stack: only the topmost trap captures, and releasing it re-arms the one beneath.

tsx

1 useFocusTrap(containerRef)

When to use it

Modal dialogs, confirmation prompts, and other surfaces that must hold focus until dismissed.
Any overlay where Tab should never reach the page behind it.

A focus trap governs Tab order; it does not close on Escape or lock scroll. Pair it with useKey for Escape-to-close and useScrollLock for background scroll. For focus restoration around triggerless UI without trapping, see useFocusRestore.

Installation

$pnpm exec dgadd add keys/focus-trap

[Installs to]src/hooks/use-focus-trap.ts[Item]keys/focus-trap

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

@diffgazer/keys requires no CSS or Tailwind setup.

Parameters

Name	Type	Default	Description
containerRefrequired	RefObject<HTMLElement \| null>	—	Ref to the container element that traps focus. Passed as the first positional argument.
options.initialFocus	RefObject<HTMLElement \| null>	—	Ref to the element that receives focus when the trap activates. Defaults to the first focusable element.
options.restoreFocus	boolean	true	Restore focus to the previously focused element when the trap deactivates.
options.enabled	boolean	true	Whether the focus trap is active.

The container ref is the first positional argument; options follow as the second argument.

Returns

voidThis hook does not return a value.

Keyboard behavior

Key	Behavior
`Tab`	Advances through tabbable elements; wraps from the last back to the first.
`Shift+Tab`	Moves backward; wraps from the first to the last.
`Tab` (no tabbables)	Prevented; focus stays on the container so the trap is never escaped.

Focusable and tabbable are treated as distinct: programmatic recapture may target a tabIndex={-1} container, while Tab cycling only visits tabbable elements. Focus detection and Tab order follow the composed tree. A trap can be rendered inside an open shadow root or contain nested open shadow roots; their tabbable descendants participate in the same order as light-DOM controls. A MutationObserver re-captures focus if the focused element is removed or becomes unfocusable.

Examples

Modal focus trap

Preview

tsx

1 "use client";2 3 import { useFocusTrap } from "@diffgazer/keys";4 import { useRef, useState } from "react";5 6 export default function UseFocusTrapBasic() {7   const [open, setOpen] = useState(false);8   const trapRef = useRef<HTMLDivElement>(null);9 10   useFocusTrap(trapRef, { enabled: open, restoreFocus: true });11 12   return (13     <div>14       <button type="button" onClick={() => setOpen(true)}>15         Open Panel16       </button>17 18       {open && (19         <div20           ref={trapRef}21           role="dialog"22           aria-modal="true"23           aria-label="Confirm action"24           tabIndex={-1}25           style={{ marginTop: 8, padding: 12, border: "1px solid currentColor" }}26         >27           <p>Tab cycles through buttons; focus is trapped here.</p>28           <button type="button" onClick={() => setOpen(false)}>29             Cancel30           </button>31           <button type="button" onClick={() => setOpen(false)}>32             Confirm33           </button>34         </div>35       )}36     </div>37   );38 }39

Custom initial focus

Preview

tsx

1 "use client";2 3 import { useFocusTrap } from "@diffgazer/keys";4 import { useRef, useState } from "react";5 6 export default function UseFocusTrapInitialFocus() {7   const [open, setOpen] = useState(false);8   const dialogRef = useRef<HTMLDivElement>(null);9   const saveRef = useRef<HTMLButtonElement>(null);10 11   // initialFocus moves focus to Save instead of the first focusable element.12   useFocusTrap(dialogRef, { enabled: open, initialFocus: saveRef, restoreFocus: true });13 14   return (15     <div>16       <button type="button" onClick={() => setOpen(true)}>17         Edit item18       </button>19 20       {open && (21         <div22           ref={dialogRef}23           role="dialog"24           aria-modal="true"25           aria-label="Save changes"26           tabIndex={-1}27           style={{ marginTop: 8, padding: 12, border: "1px solid currentColor" }}28         >29           <p>This dialog opens with focus on Save. Tab stays inside; Esc is up to you.</p>30           <button type="button" onClick={() => setOpen(false)}>31             Cancel32           </button>33           <button ref={saveRef} type="button" onClick={() => setOpen(false)}>34             Save35           </button>36         </div>37       )}38     </div>39   );40 }41

Notes

Standalone

useFocusTrap does not require KeyboardProvider. It intercepts Tab/Shift+Tab with a capture-phase keydown listener on the container's document while the trap is active, and uses a capture-phase focusin listener there to recapture escaped focus.

Tab wrapping

When focus reaches the last focusable element, Tab wraps to the first. Shift+Tab from the first wraps to the last.

Edge cases

initialFocus. Defaults to the first focusable element. Provide a ref to focus a specific control — for a destructive prompt, point it at Cancel rather than Confirm.
restoreFocus. On by default; focus returns to the element that was focused before the trap activated. When an outer trap is still active, focus returns to that trap instead of the pre-trap element.
Container tabindex. If the container has no tabindex, the hook adds tabindex="-1" while active and removes it on release so an empty trap can still hold focus.
Open shadow roots. Containers rendered inside an open shadow root and containers with nested open shadow roots use the same initial focus, composed Tab order, escape recapture, and restoration behavior as light-DOM containers. Closed shadow roots remain opaque.

useFocusRestore — restore focus without trapping Tab.
useScrollLock — lock background scroll behind a modal.
Focus and scroll guide — composing trap, restore, and scroll lock.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.