# What changed in focus-trap

> 16 changes in focus-trap 3 to 8 from its official release notes, upgrade guides and advisories: 6 breaking, 5 new APIs and options. Each one cited. Sources checked 2026-11-12. HTML: https://unstale.sh/npm/focus-trap/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## focus-trap 8

### Breaking changes

- Subtree isolation now waits for the initial focus delay before being applied. (8.0.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.0.0)
- The callback now runs after the initial focus delay, when the initial focus node has been focused and the trap is fully activated. (8.0.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.0.0)

### New APIs and options

- Adds an option, defaulting to true, to control whether return focus and onPostDeactivate are deferred by one frame. (8.2.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.2.0)
- Lifecycle hooks now receive the associated focus trap as a parameter. (8.1.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.1.0)

### Fixes and other changes

- Fixes lifecycle ordering so synchronous activation, pause, unpause, and deactivation are not delayed when the listed options and callbacks indicate synchronous behavior. (8.2.1) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.2.1)
- Improves focus handling for nested traps so a parent trap resumes using the innermost active element. (8.2.1) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.2.1)
- Fixes focus landing on the body instead of remaining in the trap when the ancestor of a focused node is removed. (8.2.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.2.0)
- Its Promise resolution type is now unknown, allowing Promise.all() and Promise.allSettled() to be returned without type issues. (8.0.1) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v8.0.1)

## focus-trap 7

### Breaking changes

- Support for all versions of IE was dropped. (7.0.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v7.0.0)
- The tabbable dependency was updated to v6.0.0, whose default displayCheck setting changes behavior related to detached nodes. (7.0.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v7.0.0)

### New APIs and options

- Adds aria-hidden support to the isolateSubtrees config option. (7.8.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v7.8.0)
- Adds the isolateSubtrees option to prevent screen readers from reading content outside the trap. (7.7.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v7.7.0)
- The updated tabbable dependency makes its new displayCheck option available through tabbableOptions. (7.6.6) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v7.6.6)

### Fixes and other changes

- Fixes an undefined method _setSubtreeIsolation crash when using trapStack in DOM with older versions of Focus-trap. (7.8.0) — [release notes](https://github.com/focus-trap/focus-trap/releases/tag/v7.8.0)

## focus-trap 3

### Breaking changes

- When clickOutsideDeactivates and returnFocusOnDeactivate are both true, focus returns to the pre-trap element only if the clicked element is not focusable. (3.0.0) — [release notes](https://github.com/focus-trap/focus-trap/blob/HEAD/CHANGELOG.md)
- Tabbable detects more elements and handles radio buttons more carefully, which can change which elements are tabbable. (3.0.0) — [release notes](https://github.com/focus-trap/focus-trap/blob/HEAD/CHANGELOG.md)