useFocusTrap API

useFocusTrap

Confines Tab / Shift+Tab to the subtree of target.

tabbable

active

Reactive activation source. When it flips true the trap engages and focuses into the root; when it flips false the trap releases and restores focus. Omit it entirely to drive the trap imperatively.

initial

Where focus lands when the trap engages. - omitted — the first tabbable descendant, falling back to the root - false — nothing is focused; the first Tab pulls focus in instead - an element / ref / getter — that node is focused directly. If it cannot take focus, the first tabbable descendant (or the root) is used instead

restore

Return focus to the element that was focused before activation. Skipped when focus already sits on an outside control by the time the trap releases — closing a dialog must not steal focus back from whatever the user just clicked. A blur to <body> still restores.

Default: true

listen

Bind the capture-phase keydown listener on document. Set false when a consumer-owned listener will call {@link UseFocusTrapReturn.onKeydown} itself — otherwise the document listener has already wrapped by the time a root handler runs. A listen: false trap is not pushed onto the nest stack.

Default: true

onEscape

Invoked on Escape while this trap is the last connected trap that has onEscape and owns focus. Opt-in and side-effect free: the trap never calls preventDefault() and never deactivates itself. An inner Tab-only trap (no onEscape) does not eat Escape — it falls through to the next connected trap that has a handler. Gate on a useStack ticket when dismissal policy is overlay-stack, not trap-stack.

isActive

Whether the trap is currently engaged

activate

Engage the trap: capture the focused element for a later restore, bind containment, and focus into the root once it exists. No-op when already engaged, so it never overwrites the captured restore target.

deactivate

Release the trap and restore focus. No-op when not engaged.

onKeydown

The keydown handler. Bound on document in the capture phase while the trap is engaged unless {@link UseFocusTrapOptions.listen} is false.