focus-trap
Advanced tools
Changelog
6.9.4
Readme
Trap focus within a DOM node.
There may come a time when you find it important to trap focus within a DOM node — so that when a user hits Tab or Shift+Tab or clicks around, she can't escape a certain cycle of focusable elements.
You will definitely face this challenge when you are trying to build accessible modals.
This module is a little, modular vanilla JS solution to that problem.
Use it in your higher-level components. For example, if you are using React check out focus-trap-react, a light wrapper around this library. If you are not a React user, consider creating light wrappers in your framework-of-choice.
When a focus trap is activated, this is what should happen:
Tab and Shift+Tab keys will cycle through the focus trap's tabbable elements but will not leave the focus trap.Escape key will deactivate the focus trap.When the focus trap is deactivated, this is what should happen:
For more advanced usage (e.g. focus traps within focus traps), you can also pause a focus trap's behavior without deactivating it entirely, then unpause at will.
npm install focus-trap
You can also use a UMD version published to unpkg.com as dist/focus-trap.umd.js and dist/focus-trap.umd.min.js.
NOTE: The UMD build does not bundle the
tabbabledependency. Therefore you will have to also include that one, and include it beforefocus-trap.
<head>
<script src="https://unpkg.com/tabbable/dist/index.umd.js"></script>
<script src="https://unpkg.com/focus-trap/dist/focus-trap.umd.js"></script>
</head>
IE9+
Why?
Because this module uses EventTarget.addEventListener().
And its only dependency, tabbable, uses a couple of IE9+ functions.
import * as focusTrap from 'focus-trap'; // ESM
const focusTrap = require('focus-trap'); // CJS
// UMD: `focusTrap` is defined as a global on `window`
trap = focusTrap.createFocusTrap(element[, createOptions]);
Returns a new focus trap on element (one or more "containers" of tabbable nodes that, together, form the total set of nodes that can be visited, with clicks or the tab key, within the trap).
element can be:
document.querySelector() to find the DOM node); orA focus trap must have at least one container with at least one tabbable/focusable node in it to be considered valid. While nodes can be added/removed at runtime, with the trap adjusting to added/removed tabbable nodes, an error will be thrown if the trap ever gets into a state where it determines none of its containers have any tabbable nodes in them and the
fallbackFocusoption does not resolve to an alternate node where focus can go.
{() => void}: A function that will be called before sending focus to the target element upon activation.{() => void}: A function that will be called after sending focus to the target element upon activation.{(containers: Array<HTMLElement | SVGElement>) => Promise<void>}: Animated dialogs have a small delay between when onActivate is called and when the focus trap is focusable. checkCanFocusTrap expects a promise to be returned. When that promise settles (resolves or rejects), focus will be sent to the first tabbable node (in tab order) in the focus trap (or the node configured in the initialFocus option). Due to the lack of Promise support, checkCanFocusTrap is not supported in IE unless you provide a Promise polyfill.{() => void}: A function that will be called before returning focus to the node that had focus prior to activation (or configured with the setReturnFocus option) upon deactivation.{() => void}: A function that will be called after the trap is deactivated, after onDeactivate. If the returnFocus deactivation option was set, it will be called after returning focus to the node that had focus prior to activation (or configured with the setReturnFocus option) upon deactivation; otherwise, it will be called after deactivation completes.{(trigger: HTMLElement | SVGElement) => Promise<void>}: An animated trigger button will have a small delay between when onDeactivate is called and when the focus is able to be sent back to the trigger. checkCanReturnFocus expects a promise to be returned. When that promise settles (resolves or rejects), focus will be sent to to the node that had focus prior to the activation of the trap (or the node configured in the setReturnFocus option). Due to the lack of Promise support, checkCanReturnFocus is not supported in IE unless you provide a Promise polyfill.{HTMLElement | SVGElement | string | false | (() => HTMLElement | SVGElement | string | false)}: By default, when a focus trap is activated the first element in the focus trap's tab order will receive focus. With this option you can specify a different element to receive that initial focus. Can be a DOM node, or a selector string (which will be passed to document.querySelector() to find the DOM node), or a function that returns any of these. You can also set this option to false (or to a function that returns false) to prevent any initial focus at all when the trap activates.
false (or a function that returns false) will prevent the fallbackFocus option from being used.{HTMLElement | SVGElement | string | () => HTMLElement | SVGElement | string}: By default, an error will be thrown if the focus trap contains no elements in its tab order. With this option you can specify a fallback element to programmatically receive focus if no other tabbable elements are found. For example, you may want a popover's <div> to receive focus if the popover's content includes no tabbable elements. Make sure the fallback element has a negative tabindex so it can be programmatically focused. The option value can be a DOM node, a selector string (which will be passed to document.querySelector() to find the DOM node), or a function that returns any of these.
initialFocus is false (or a function that returns false), this function will not be called when the trap is activated, and no element will be initially focused. This function may still be called while the trap is active if things change such that there are no longer any tabbable nodes in the trap.{boolean} | (e: KeyboardEvent) => boolean): Default: true. If false or returns false, the Escape key will not trigger deactivation of the focus trap. This can be useful if you want to force the user to make a decision instead of allowing an easy way out. Note that if a function is given, it's only called if the ESC key was pressed.{boolean | (e: MouseEvent | TouchEvent) => boolean}: If true or returns true, a click outside the focus trap will immediately deactivate the focus trap and allow the click event to do its thing (i.e. to pass-through to the element that was clicked). This option takes precedence over allowOutsideClick when it's set to true. Default: false.
mousedown (or touchstart on mobile) event and, if true was returned, again on the click event. It will get the same node each time, and it's recommended that the returned value is also the same each time. Be sure to check the event type if the double call is an issue in your code.allowOutsideClick option to better control exactly when the focus trap can be deactivated. The clickable icons are usually positioned absolutely, floating on top of the fields, and therefore not part of the container the trap is managing. When using the clickOutsideDeactivates option, clicking on a field's 1Password icon will likely cause the trap to be unintentionally deactivated.{boolean | (e: MouseEvent | TouchEvent) => boolean}: If set and is or returns true, a click outside the focus trap will not be prevented (letting focus temporarily escape the trap, without deactivating it), even if clickOutsideDeactivates=false. Default: false.
mousedown (or touchstart on mobile), and then on the actual click if the function returned true on the first event. Be sure to check the event type if the double call is an issue in your code.clickOutsideDeactivates=true, this option is ignored (i.e. if it's a function, it will not be called).clickOutsideDeactivates=false.{boolean}: Default: true. If false, when the trap is deactivated, focus will not return to the element that had focus before activation.{HTMLElement | SVGElement | string | (previousActiveElement: HTMLElement | SVGElement) => HTMLElement | SVGElement | string | false}: By default, on deactivation, if returnFocusOnDeactivate=true (or if returnFocus=true in the deactivation options), focus will be returned to the element that was focused just before activation. With this option, you can specify another element to programmatically receive focus after deactivation. It can be a DOM node, a selector string (which will be passed to document.querySelector() to find the DOM node upon deactivation), or a function that returns any of these to call upon deactivation (i.e. the selector and function options are only executed at the time the trap is deactivated). Can also be false (or return false) to leave focus where it is at the time of deactivation.
{boolean}: By default, focus() will scroll to the element if not in viewport. It can produce unintended effects like scrolling back to the top of a modal. If set to true, no scroll will happen.{boolean}: Default: true. Delays the autofocus to the next execution frame when the focus trap is activated. This prevents elements within the focusable element from capturing the event that triggered the focus trap activation.window.document. Document where the focus trap will be active. This allows to use FocusTrap in an iFrame context.⚠️ Beware that putting a focus-trap inside an open Shadow DOM means you must either:
document.querySelector()); ORdocument option to configure the focus trap to use your shadow host element as its document. The downside of this option is that, while selector queries on nodes inside your trap will now work, the trap will not prevent focus from being set on nodes outside your Shadow DOM, which is the same drawback as putting a focus trap inside an iframe.If you have closed shadow roots that you would like considered for tabbable/focusable nodes, use the tabbableOptions.getShadowRoot option to provide Tabbable (used internally) with a reference to a given node's shadow root so that it can be searched for candidates.
trap.active: boolean
True if the trap is currently active.
trap.paused: boolean
True if the trap is currently paused.
trap.activate([activateOptions]) => FocusTrap
Activates the focus trap, adding various event listeners to the document.
If focus is already within it the trap, it remains unaffected. Otherwise, focus-trap will try to focus the following nodes, in order:
createOptions.initialFocuscreateOptions.fallbackFocusIf none of the above exist, an error will be thrown. You cannot have a focus trap that lacks focus.
Returns the trap.
activateOptions:
These options are used to override the focus trap's default behavior for this particular activation.
{() => void}: Default: whatever you chose for createOptions.onActivate. null or false are the equivalent of a noop.{() => void}: Default: whatever you chose for createOptions.onPostActivate. null or false are the equivalent of a noop.{(containers: Array<HTMLElement | SVGElement>) => Promise<void>}: Default: whatever you chose for createOptions.checkCanFocusTrap.trap.deactivate([deactivateOptions]) => FocusTrap
Deactivates the focus trap.
Returns the trap.
deactivateOptions:
These options are used to override the focus trap's default behavior for this particular deactivation.
{boolean}: Default: whatever you set for createOptions.returnFocusOnDeactivate. If true, then the setReturnFocus option (specified when the trap was created) is used to determine where focus will be returned.{() => void}: Default: whatever you set for createOptions.onDeactivate. null or false are the equivalent of a noop.{() => void}: Default: whatever you set for createOptions.onPostDeactivate. null or false are the equivalent of a noop.{(trigger: HTMLElement | SVGElement) => Promise<void>}: Default: whatever you set for createOptions.checkCanReturnFocus. Not called if the returnFocus option is falsy. trigger is either the originally focused node prior to activation, or the result of the setReturnFocus configuration option.trap.pause() => FocusTrap
Pause an active focus trap's event listening without deactivating the trap.
If the focus trap has not been activated, nothing happens.
Returns the trap.
Any onDeactivate callback will not be called, and focus will not return to the element that was focused before the trap's activation. But the trap's behavior will be paused.
This is useful in various cases, one of which is when you want one focus trap within another. demo-six exemplifies how you can implement this.
trap.unpause() => FocusTrap
Unpause an active focus trap. (See pause(), above.)
Focus is forced into the trap just as described for focusTrap.activate().
If the focus trap has not been activated or has not been paused, nothing happens.
Returns the trap.
trap.updateContainerElements() => FocusTrap
Update the element(s) that are used as containers for the focus trap.
When you call the function createFocusTrap, you pass in an element (or selector), or an array of elements (or selectors) to keep the focus within. This method simply allows you to update which elements to keep the focus within.
A use case for this is found in focus-trap-react, where React ref's may not be initialized yet, but when they are you want to have them be a container element.
Returns the trap.
Read code in docs/ and see how it works.
Here's generally what happens in default.js (the "default behavior" demo):
const { createFocusTrap } = require('../../index');
const container = document.getElementById('default');
const focusTrap = createFocusTrap('#default', {
onActivate: () => container.classList.add('is-active'),
onDeactivate: () => container.classList.remove('is-active'),
});
document
.getElementById('activate-default')
.addEventListener('click', focusTrap.activate);
document
.getElementById('deactivate-default')
.addEventListener('click', focusTrap.deactivate);
Only one focus trap can be listening at a time. If a second focus trap is activated the first will automatically pause. The first trap is unpaused and again traps focus when the second is deactivated.
Focus trap manages a queue of traps: if A activates; then B activates, pausing A; then C activates, pausing B; when C then deactivates, B is unpaused; and when B then deactivates, A is unpaused.
The focus trap will work best if the first and last focusable elements in your trap are simple elements that all browsers treat the same, like buttons and inputs.**
Tabbing will work as expected with trickier, less predictable elements — like iframes, shadow trees, audio and video elements, etc. — as long as they are between more predictable elements (that is, if they are not the first or last tabbable element in the trap).
This limitation is ultimately rooted in browser inconsistencies and inadequacies, but it comes to focus-trap through its dependency Tabbable. You can read about more details in the Tabbable documentation.
You can't have a focus trap without focus, so an error will be thrown if you try to initialize focus-trap with an element that contains no tabbable nodes.
If you find yourself in this situation, you should give you container tabindex="-1" and set it as initialFocus or fallbackFocus. A couple of demos illustrate this.
Because of the nature of the functionality, involving keyboard and click and (especially) focus events, JavaScript unit tests don't make sense. After all, JSDom does not fully support focus events. Since the demo was developed to also be the test, we use Cypress to automate running through all demos in the demo page.
⚠️ JSDom is not officially supported. Your mileage may vary, and tests may break from one release to the next (even a patch or minor release).
This topic is just here to help with what we know may affect your tests.
In general, a focus trap is best tested in a full browser environment such as Cypress, Playwright, or Nightwatch where a full DOM is available.
Sometimes, that's not entirely desirable, and depending on what you're testing, you may be able to get away with using JSDom (e.g. via Jest), but you'll have to configure your traps using the tabbableOptions.displayCheck: 'none' option.
See Testing tabbable in JSDom for more details.
See CONTRIBUTING.
In alphabetical order:
FAQs
Trap focus within a DOM node.
We found that focus-trap demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.
Security News
Socket is joining forces with CISA and other industry leaders at the RSA Conference to sign the Secure by Design pledge, committing to uphold the highest security standards in our products.
Research
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.
