npm / focus-trap
focus-trap
What changed in focus-trap 3 to 8, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-12.
6 breaking5 new APIs and options5 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initfocus-trap 88 changes
Breaking changes 2
Subtree isolation now waits for the initial focus delay before being applied.
The callback now runs after the initial focus delay, when the initial focus node has been focused and the trap is fully activated.
New APIs and options 2
Adds an option, defaulting to true, to control whether return focus and onPostDeactivate are deferred by one frame.
Lifecycle hooks now receive the associated focus trap as a parameter.
Fixes and other changes 4
Fixes lifecycle ordering so synchronous activation, pause, unpause, and deactivation are not delayed when the listed options and callbacks indicate synchronous behavior.
Improves focus handling for nested traps so a parent trap resumes using the innermost active element.
Fixes focus landing on the body instead of remaining in the trap when the ancestor of a focused node is removed.
Its Promise resolution type is now unknown, allowing Promise.all() and Promise.allSettled() to be returned without type issues.
focus-trap 76 changes
Breaking changes 2
Support for all versions of IE was dropped.
The tabbable dependency was updated to v6.0.0, whose default displayCheck setting changes behavior related to detached nodes.
New APIs and options 3
Adds aria-hidden support to the isolateSubtrees config option.
Adds the isolateSubtrees option to prevent screen readers from reading content outside the trap.
The updated tabbable dependency makes its new displayCheck option available through tabbableOptions.
Fixes and other changes 1
Fixes an undefined method _setSubtreeIsolation crash when using trapStack in DOM with older versions of Focus-trap.
focus-trap 32 changes
Breaking changes 2
When clickOutsideDeactivates and returnFocusOnDeactivate are both true, focus returns to the pre-trap element only if the clicked element is not focusable.
Tabbable detects more elements and handles radio buttons more carefully, which can change which elements are tabbable.