NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #4193 most downloaded on npm
Trap focus within a DOM node.
Last release today
04 Oct 2026
Release timing varies
gaps range from 9 days to 5 months
Nearly every release is documented
notes for 59 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
97 releases · first in 2015
Nothing published for this version
859bda8: Update tabbable to v6.5.0 for visibility fix and image map support
7e0e518: Fixes lifecycle ordering bug introduced in v8.0.0 that always delays the order even if delayInitialFocus=false, delayReturnFocus=false, check
delayInitialFocus=false, delayReturnFocus=false, checkCanFocusTrap=undefined, checkCanReturnFocus=undefined (which would indicate a fully synchronous activation/pause/unpause/deactivation process) #1862One column per quarter.
567dbe1: Add new delayReturnFocus option (default true) to control whether return focus and onPostDeactivate are deferred by one frame (#1689).
delayReturnFocus option (default true) to control whether return focus and onPostDeactivate are deferred by one frame (#1689).642f7f2: Update lifecycle hooks to include the associated focus trap as a parameter.
7d5010e: Loosen checkCanFocusTrap Promise resolution type to unknown to make it easier to use Promise.all() or Promise.allSettled() as the returned Pr
unknown to make it easier to use Promise.all() or Promise.allSettled() as the returned Promise (Promise<void> was causing issues because those Promise APIs do not resolve with a void value).b6ea4b5: Breaking: Fixed a long-standing bug where onPostActivate() would be called _before_ the initial focus node was focused and the trap was fully
onPostActivate() would be called before the initial focus node was focused and the trap was fully activated. (#1747)
setTimeout(0)) but wasn't delaying calling onPostActivate() until after that delay.isolateSubtrees='aria-hidden' option, the currently-focused node's container (a non-subtree being "disabled") would get hidden before the delay was up, resulting in Chrome preventing the effect of aria-hidden on that subtree with a warning in the console due to the container being hidden still containing focus (e.g. the "activate trap" button).onPostActivate() await the initial focus delay (if there is one, which is default behavior; remove it with delayInitialFocus=false) before being applied/called.await waitFor(() => expect(initialFocusNode).toBeFocused()).onPostActivate() handler (prior to this change, that node would not be focused yet; after this change, it will be focused).c214581: Adds aria-hidden support to isolateSubtrees config option
_setSubtreeIsolation crash when using trapStack in DOM with older versions of Focus-trap (#1729)a386578: Bump tabbable dependency for improved inert handling
14b9155: Adds a new feature "isolateSubtrees", allowing focus-trap to prevent screen readers from reading content outside the trap.
dcd4ae9: Update tabbable dependency to 6.3.0 for new displayCheck option.
tabbable dependency to 6.3.0 for new displayCheck option.d51ad78: Allow activation element in shadow DOM to be auto-focused after trap is deactivated
bb47f7a: Remove engine requirement that crept into package.json. Sorry about that!
package.json. Sorry about that! (#1343)0a9b746: Prevent a previous focus trap that is manually paused from being automatically unpaused when the current trap is deactivated. Also prevent a
d4a4c34: Replace findIndex with native implementation - [Closes #1305]\(
fc5910d: Fix fallbackFocus not used when initialFocus is selector to non-existent node
8aeacee: Move Escape key handler to target phase to allow more control in escapeDeactivates
Escape key handler to target phase to allow more control in escapeDeactivates (#1247)680f6e8: Fix issue with not being able to cycle back to the start from the last element if there is a focusable web component inside the focus-trap ((
203b322: Fix missing typings for initialFocus option
b73eb02: Remove references to Array.prototype.findLast() not well supported in Safari
Array.prototype.findLast() not well supported in Safari (#996)d9e2546: Fix possible exception in new Tabbable.getTabIndex() when initializing trap
Tabbable.getTabIndex() when initializing trap5e2f913: Adds support for nodes with a positive tabindex in single-container traps only
134678b: Ensure focus is kept inside the trap when focused element is removed from the DOM (focus-trap/focus-trap-react#962)
db62ce3: Clicking on open shadowDOM components within a focus trap's container when clickOutsideDeactivates=true should not deactivate the focus trap.
clickOutsideDeactivates=true should not deactivate the focus trap. (#959)4f720ff: Bump tabbable to v6.1.2 for nwsapi patch
da97007: Added new onPost/Pause and onPost/Unpause hooks when un/pausing a trap (also called when auto-un/paused as a result of de/activating a second
a00cfa5: Bump tabbable to v6.1.1 for JSDom fixes
ae7129d: Bump tabbable to v6.1.0 adding support for the new HTML inert attribute in browsers that support it (NOTE: FireFox does not support it at thi
inert attribute in browsers that support it (NOTE: FireFox does not support it at this time). Also fixes a bug. See tabbable CHANGELOG for more info.returnFocusOnDeactivate option when set to true (or defaulted to true) along with clickOutsideDeactivates=true and the outside click that deactivates is on a focusable node. Focus was remaining on that node instead of returning to the node focused just prior to activation. (#893)Nothing published for this version
Nothing published for this version
Nothing published for this version
b0482af: Add new isKeyForward() and isKeyBackward() options
isKeyForward() and isKeyBackward() options (#612)88cc9bc: Provide new trapStack option to make it possible to coordinate auto-activation/pausing between multiple focus-trap instances on the same page
trapStack option to make it possible to coordinate auto-activation/pausing between multiple focus-trap instances on the same page.47f62ac: 🚨 Breaking: Tabbable dependency has been updated to v6.0.0 and contains a breaking change related to detached nodes with its default displayC…
displayCheck setting. See tabbable's changelog for more information.f68882e: Fix docs and typings to clarify that initialFocus, fallbackFocus, and setReturnFocus options can be functions that also return selector strin
8a8b1f1: Bump tabbable to v5.3.3 to pick up a small bug fix to web component (shadow DOM) support.
ef0ce48: Handle unexpected param (true) passed as the value for the initialFocus, fallbackFocus, and setReturnFocus options: Ignore and perform defaul
initialFocus, fallbackFocus, and setReturnFocus options: Ignore and perform default behavior.83262a7: Bumps tabbable to v5.3.2 to pick-up a fix to displayCheck=full (default) option behavior that caused issues with detached nodes.
displayCheck=full (default) option behavior that caused issues with detached nodes.2a57e4b: Add new trap.active and trap.paused readonly state properties on the trap so that the trap's active/paused state can be queried.
trap.active and trap.paused readonly state properties on the trap so that the trap's active/paused state can be queried.clickOutsideDeactivate handler would get called on the 'click' event even if the node clicked was in the trap. As with 'mousedown' and 'touchstart' events where this option is also used, the handler should only get called if the target node is outside the trap.trap.deactivate({...}) with an option set even if that option set didn't specify any overrides of these options.Bump tabbable to ^5.3.1 (fixing previous update which was incorrectly set to 5.3.0).
^5.3.1 (fixing previous update which was incorrectly set to 5.3.0).tabbableOptions not being used in all internal uses of tabbable APIs.displayCheck option in tabbableOptions typings and pass it through to tabbable APIs.21458c9: Bumps tabbable to v5.3.0 and includes all changes from the past v6.8.0 beta releases. The big new feature is opt-in Shadow DOM support in tab
getShadowRoot tabbable option exposed in a new tabbableOptions focus-trap config option.getShadowRoot tabbable option exposed in a new tabbableOptions focus-trap config option.
When updating tabbable nodes, make sure that getShadowRoot tabbable option is also passed to focusable().
getShadowRoot tabbable option is also passed to focusable().v5.3.0-beta.1Previous beta didn't include new source. This one does.
Adds new tabbableOptions configuration option, which allows specifically for the new getShadowRoot Tabbable configuration option: focusTrap.createFocu
tabbableOptions configuration option, which allows specifically for the new getShadowRoot Tabbable configuration option: focusTrap.createFocusTrap(rootElement, { tabbableOptions: { getShadowRoot: (node) => closedShadowRoot } }), for example (where your code has the reference to closedShadowRoot previously created on node which Tabbable cannot find on its own).v5.3.0-beta.0ab20d3d: Fix issue with focusing negative tabindex node and then tabbing away when this node is _not_ the last node in the trap's container ((#611)[ht
c932330: Fixed bug where tabbing forward from an element with negative tabindex that is last in the trap would result in focus remaining on that eleme
28a069f: Fix bug from #504 where it's no longer possible to create a trap without any options [#525]
893dd2c: Add document option to support focus traps inside elements
document option to support focus traps inside <iframe> elements (#97)setReturnFocus option to receive a reference to the element that had focus prior to the trap being activated when a function is specified. Additionally, the function can now return false to leave focus where it is at the time of deactivation. (#485)KeyboardEvent was not being passed to escapeDeactivates option when it's a function (#498)initialFocus option not supporting function returning false as documented (#490)24063d7: Update tabbable to v5.2.1 to get bug fix for disabled fieldsets.
281e66c: Add option to allow no initial focus when trap activates via initialFocus: false
281e66c: Add option to allow no initial focus when trap activates via initialFocus: false
There may be cases where we don't want to focus the first tabbable element when a focus trap activates.
Examples use-cases:
In addition, this change ensures that any element inside the trap manually focused outside of focus-trap code will be brought back in focus if focus is somehow found outside of the trap.
Example usage:
When the trap activates, there will be no initially focused element inside the new trap.
const focusTrap = createFocusTrap('#some-container', {
initialFocus: false,
});
75be463: escapeDeactivates can now be either a boolean (as before) or a function that takes an event and returns a boolean.
delayInitialFocus timer created for the second trap before during its activation sequence.c38bf3f: onPostDeactivate should always be called even if returnFocus/OnDeactivate is disabled.
278e77e: Adding 4 new configuration event options to improve support for animated dialogs and animated focus trap triggers: checkCanFocusTrap(), onPos
checkCanFocusTrap(), onPostActivate(), checkCanReturnFocus(), and onPostDeactivate().SVGElement as a supported type of "DOM node" since it supports the focus() method, same as HTMLElement.<area> elements with an href attribute (image map hotspots),visibility: collapse as hidden, the same way visibility: hidden is already handled, so they are no longer considered tabbable or focusable. This matches browser behavior, where collapse hides an element (outside of table rows/columns) just like hidden.21c82ce: Bump tabbable from 5.1.6 to 5.2.0. There should be no changes in behavior as a result of this upgrade as focus-trap does not currently levera
focus-trap does not currently leverage the new displayCheck option.26a1d80: Enable CSS selector matching for whether an element is in an inert subtree ([inert] *).
This was previously disabled due to JSDOM's CSS selector engine being incompatible with this selector, and throwing all the results off. Instead, tabbable would perform manual checks for an element being in an inert subtree. The CSS selector issue appears to have been fixed in recent JSDOM versions (at least 26), so this version reintroduces the selector fast path.
a882d62: clickOutsideDeactivates can now also be a function that returns a boolean, similar to allowOutsideClick. The function receives the MouseEvent
clickOutsideDeactivates can now also be a function that returns a boolean, similar to allowOutsideClick. The function receives the MouseEvent that triggered the click. (#289)displayCheck option, utilising Element#checkVisibility036a72e: Fix crash in IE due to use of Array.findIndex() not supported in that browser
Array.findIndex() not supported in that browser (#257)fd3f2d1: Fix a bug where a multi-container trap would cease to work if all tabbable nodes were removed from one of the containers (fixes #223). As a r
fallbackFocus node has been configured in the trap's options). Also, the most-recently-focused node is more reliably tracked now, should focus somehow escape the trap and be brought back in by the trap, resulting in the truly most-recently-focused node to regain focus if that ever happens.f0c2aff: Bump tabbable to 5.1.4 for bug fix.
./dist.trap.activate() and trap.deactivate() would not always return the trap (now they do in all circumstances)../dist, however, and hence does not impact browser support.2267d17: Adding support for multiple elements to be passed in #217
getTabIndex() API which enables Focus-trap to determine tab indexes in the same way as Tabbable when necessary (see focus-trap#974).38b6b98: Update tabbable to 5.1.3 to get bug fixes related to detail and summary elements.
6a39217: Close the gap with #172 and bump tabbable to 5.1.2 which has a similar fix.
tabbable to 5.1.2 which has a similar fix.Your coding agent can read these notes before it upgrades. Set up the MCP server →