focus-trap-react
v10.0.3-tabbable-i905.2TypeScript
A React component that traps focus.
0/weekUpdated 1 weeks agoMITUnpacked: 87.9 KB
Published by David Clark
npm install focus-trap-reactfocus-trap-react   
A React component that traps focus.
This component is a light wrapper around focus-trap,
tailored to your React-specific needs.
You might want it for, say, building an accessible modal?
What it does
Please read the focus-trap documentation to understand what a focus trap is, what happens when a focus trap is activated, and what happens when one is deactivated.
This module simply provides a React component that creates and manages a focus trap.
- The focus trap automatically activates when mounted (by default, though this can be changed).
- The focus trap automatically deactivates when unmounted.
- The focus trap can be activated and deactivated, paused and unpaused via props.
Installation
``
npm install focus-trap-react
dist/focus-trap-react.js is the Babel-compiled file that you'll use.
$3
React >= 18.0.0
> Note that while React 18.x still supported propTypes and defaultProps, they had long-since been deprecated, and are completely dropped in React 19.
Therefore, this library no longer assigns these properties to the element for runtime validation and initialization. The same techniques you would now use in React 19 are backward-compatible with React 18:
- Use TypeScript for static prop type validation
- Use a runtime validation library such as RTV.js, JSON Schema, or yup for runtime prop validation to replace prop-types)
> This library aims to support one major version of React _behind_ the current major version, since React major releases are typically years apart -- to the extent that the feature drift is not too great and remains reasonably surmountable.
Browser Support
Focused on desktop browsers, particularly Chrome, Edge, FireFox, Safari, and Opera.
Gated by what React supports in the version currently supported.
Focus-trap-react is not officially tested on any mobile browsers or devices.
> ⚠️ Microsoft no longer supports any version of IE, so IE is no longer supported by this library.
> 💬 Focus-trap-react relies on focus-trap so its browser support is at least what focus-trap supports.
> 💬 Keep in mind that performance optimization and old browser support are often at odds, so tabbable may not always be able to use the most optimal (typically modern) APIs in all cases.
Usage
You wrap any element that you want to act as a focus trap with the component. expects exactly one child element which can be any HTML element or other React component that contains focusable elements. __It cannot be a Fragment__ because needs to be able to get a reference to the underlying HTML element, and Fragments do not have any representation in the DOM.
For example:
`js`
`js`
You can read further code examples in demo/ (it's very simple), and see how it works.
Here's one more simple example:
`jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import { FocusTrap } from 'focus-trap-react';
class Demo extends React.Component {
constructor(props) {
super(props);
this.state = {
activeTrap: false
};
this.mountTrap = this.mountTrap.bind(this);
this.unmountTrap = this.unmountTrap.bind(this);
}
mountTrap = () => {
this.setState({ activeTrap: true });
};
unmountTrap = () => {
this.setState({ activeTrap: false });
};
render() {
const trap = this.state.activeTrap
?
onDeactivate: this.unmountTrap
}}
>
: false;
return (
{trap}
);
}
}
createRoot(document.getElementById('root')).render(
`
❗️❗️ React 18 Strict Mode ❗️❗️
React 18 introduced new behavior in Strict Mode whereby it mimics a possible future behavior where React might optimize an app's performance by unmounting certain components that aren't in use and later remounting them with previous, reused state when the user needs them again. What constitutes "not in use" and "needs them again" is as yet undefined.
_Remounted with reused state_ is the key difference between what is otherwise expected about unmounted components.
__v9.0.2 adds support__ for this new Strict Mode behavior: The trap attempts to detect that it has been remounted with previous state: If the active prop's value is true, and an internal focus trap instance already exists, the focus trap is re-activated on remount in order to reconcile stated expectations.
> 🚨 In Strict Mode (and so in dev builds only, since this behavior of Strict Mode only affects dev builds), the trap __will be deactivated as soon as it is mounted__, and then reactivated again, almost immediately, because React will immediately unmount and remount the trap as soon as it's rendered.
Therefore, __avoid using options like onActivate, onPostActivate, onDeactivate, or onPostDeactivate to affect component state__.
Explanation and sample anti-pattern to avoid
See this discussion for an example sandbox (issue description) where onDeactivate was used to trigger the close of a dialog when the trap was deactivated (e.g. to react to the user clicking outside the trap with focusTrapOptions.clickOutsideDeactivates=true).
The result can be that (depending on how you render the trap) in Strict Mode, the dialog never appears because it gets closed as soon as the trap renders, since the trap is deactivated as soon as it's unmounted, and so the onDeactivate handler is called, thus hiding the dialog...
This is intentional: If the trap gets unmounted, it has no idea if it's being unmounted for good or if it's going to be remounted at some future point in time. It also has no idea of knowing how long it will be until it's remounted again. So it must be deactivated as though it's going away for good in order to prevent unintentional behavior and memory leaks (from orphaned document event listeners).
Props
$3
> ⚠️ The component requires a __single__ child, and this child must __forward refs__ onto the element which will ultimately be considered the trap's container. Since React does not provide for a way to forward refs to class-based components, this means the child must be a __functional__ component that uses the React.forwardRef() API.containerElements
>
> If you must use a __class__-based component as the trap's container, then you will need to get your own ref to it upon render, and use the prop (initially set to an empty array []) in order to provide the ref's element to it once updated by React (hint: use a callback ref).
> 💬 The child is ignored (but still rendered) if the containerElements prop is used to imperatively provide trap container elements.
Example:
`jsx
import { forwardRef, Component } from 'react';
import { createRoot } from 'react-dom/client';
import { FocusTrap } from 'focus-trap-react';
const container = document.getElementById('demo-function-child');
const TrapChild = forwardRef(function ({ onDeactivate }, ref) {
return (
Here is a focus trap with some{' '}
focusable parts.
aria-describedby="class-child-heading"
>
deactivate trap
);
});
TrapChild.displayName = 'TrapChild';
TrapChild.propTypes = {
onDeactivate: propTypes.func,
};
class DemoFunctionChild extends Component {
constructor(props) {
super(props);
this.state = {
activeTrap: false,
};
this.mountTrap = this.mountTrap.bind(this);
this.unmountTrap = this.unmountTrap.bind(this);
}
mountTrap() {
this.setState({ activeTrap: true });
}
unmountTrap() {
this.setState({ activeTrap: false });
}
render() {
const trap = this.state.activeTrap && (
onDeactivate: this.unmountTrap,
}}
>
);
return (
{trap}
);
}
}
const root = createRoot(container);
root.render(
`
$3
Type: Object, optional
Pass any of the options available in focus-trap's createOptions.
> ❗️ This prop is __only read once__ on the first render. It's never looked at again. This is particularly important if you use state-dependent memoized __React Hooks__ (e.g. const onActivate = useCallback(() => {...}, [something])) for any of the focus-trap callbacks like onActivate(), onDeactivate(), clickOutsideDeactivates(), etc.class
>
> If you need state-dependent callbacks, you have two options: __(1)__ Use a React component (as in the examples in this README) with bound member handlers, or __(2)__ use a React Ref like useRef({ myState: 1 }) in your callbacks and manually manage your state.
>
> See #947 for more details.
> ⚠️ See notes about __testing in JSDom__ (e.g. using Jest) if that's what you currently use.
$3
Type: Boolean, optional
By default, the FocusTrap activates when it mounts. So you activate and deactivate it via mounting and unmounting. If, however, you want to keep the FocusTrap mounted while still toggling its activation state, you can do that with this prop.
See demo/demo-special-element.js.
$3
Type: Boolean, optional
If you would like to pause or unpause the focus trap (see focus-trap's documentation), toggle this prop.
$3
Type: Array of HTMLElement, optional
If specified, these elements will be used as the boundaries for the focus-trap, __instead of the child__. These get passed as arguments to focus-trap's updateContainerElements() method.
> 💬 Note that when you use containerElements, the need for a child is eliminated as the child is __always__ ignored (though still rendered) when the prop is specified, even if this prop is [] (an empty array).containerElements={[ref1.current, ref2.current]}
>
> Also note that if the refs you're putting into the array, like , aren't resolved yet, resulting in [null, null] for example, the trap will not get created. The array must contain at least one valid HTMLElement in order for the trap to get created/updated.
If containerElements is subsequently updated (i.e. after the trap has been created) to an empty array (or an array of falsy values like [null, null]), the trap will still be active, but the TAB key will do nothing because the trap will not contain any tabbable groups of nodes. At this point, the trap can either be deactivated manually or by unmounting, or an updated set of elements can be given to containerElements to resume use of the TAB key.
Using containerElements does require the use of React refs which, by nature, will require at least one state update in order to get the resolved elements into the prop, resulting in at least one additional render. In the normal case, this is likely more than acceptable, but if you really want to optimize things, then you could consider using focus-trap directly (see Trap2.js).
Help
$3
> ⚠️ 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 focusTrapOptions.tabbableOptions.displayCheck: 'none'` option.
See Testing focus-trap in JSDom for more details.
Contributing
See CONTRIBUTING.
Contributors
In alphabetical order:
