README.md

focus-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

Check out the demo.

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.

React dependency

React >= 16.3.0

Browser Support

As old and as broad as reasonably possible, excluding browsers that are out of support or have nearly no user base.

Focused on desktop browsers, particularly Chrome, Edge, FireFox, Safari, and Opera.

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 <FocusTrap> component. <FocusTrap> 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 <FocusTrap> 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:

<FocusTrap>
  <div id="modal-dialog" className="modal" >
    <button>Ok</button>
    <button>Cancel</button>
  </div>
</FocusTrap>

<FocusTrap>
  <ModalDialog okButtonText="Ok" cancelButtonText="Cancel" />
</FocusTrap>

You can read further code examples in demo/ (it's very simple), and see how it works.

Here's one more simple example:

const React = require('react');
const ReactDOM = require('react-dom'); // React 16-17
const { createRoot } = require('react-dom/client'); // React 18
const FocusTrap = require('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
      ? <FocusTrap
          focusTrapOptions={{
            onDeactivate: this.unmountTrap
          }}
        >
          <div className="trap">
            <p>
              Here is a focus trap
              {' '}
              <a href="#">with</a>
              {' '}
              <a href="#">some</a>
              {' '}
              <a href="#">focusable</a>
              {' '}
              parts.
            </p>
            <p>
              <button onClick={this.unmountTrap}>
                deactivate trap
              </button>
            </p>
          </div>
        </FocusTrap>
      : false;

    return (
      <div>
        <p>
          <button onClick={this.mountTrap}>
            activate trap
          </button>
        </p>
        {trap}
      </div>
    );
  }
}

ReactDOM.render(<Demo />, document.getElementById('root')); // React 16-17
createRoot(document.getElementById('root')).render(<Demo />); // React 18

❗️❗️ 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

children

⚠️ The <FocusTrap> 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.

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 containerElements 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:

const React = require('react');
const { createRoot } = require('react-dom/client');
const propTypes = require('prop-types');
const FocusTrap = require('../../dist/focus-trap-react');

const container = document.getElementById('demo-function-child');

const TrapChild = React.forwardRef(function ({ onDeactivate }, ref) {
  return (
    <div ref={ref}>
      <p>
        Here is a focus trap <a href="#">with</a> <a href="#">some</a>{' '}
        <a href="#">focusable</a> parts.
      </p>
      <p>
        <button
          onClick={onDeactivate}
          aria-describedby="class-child-heading"
        >
          deactivate trap
        </button>
      </p>
    </div>
  );
});

TrapChild.displayName = 'TrapChild';
TrapChild.propTypes = {
  onDeactivate: propTypes.func,
};

class DemoFunctionChild 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 && (
      <FocusTrap
        focusTrapOptions={{
          onDeactivate: this.unmountTrap,
        }}
      >
        <TrapChild />
      </FocusTrap>
    );

    return (
      <div>
        <p>
          <button onClick={this.mountTrap} aria-describedby="function-child-heading">
            activate trap
          </button>
        </p>
        {trap}
      </div>
    );
  }
}

const root = createRoot(container);
root.render(<DemoFunctionChild />);

focusTrapOptions

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.

If you need state-dependent callbacks, you have two options: (1) Use a React component class (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.

active

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.

paused

Type: Boolean, optional

If you would like to pause or unpause the focus trap (see focus-trap's documentation), toggle this prop.

containerElements

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).

Also note that if the refs you're putting into the array, like containerElements={[ref1.current, ref2.current]}, 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

Testing in JSDom

⚠️ 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:

Alex Dawson 📖	Benjamin Koltes 🐛	Benjamin Tan 📖	Clint Goodman 💻 📖 💡 ⚠️	Daniel 🚧 ⚠️	Daniel Tonon 📖 💻 ⚠️	David Clark 💻 🐛 🚇 ⚠️ 📖 🚧
Dependabot 🚧	Johannes Ewald 💻	Jonathan Suzuki 🐛	Kasper Garnæs 🐛	Kathleen McMahon 🚧	LoganDark 🐛	Marais Rossouw 🚇
Michael 💡	Misha Moroshko 🐛	Nate Liu ⚠️	Rivaldo Junior 🚧	Scott Rippey 💻 🐛	Sean McPherson 💻	Shane Moore 📦
Slapbox 📖 🐛	Stefan Cameron 💻 🐛 🚇 ⚠️ 📖 🚧	Tyler Hawkins 📖 💡 ⚠️ 🔧	Wandrille Verlut 💻 ⚠️	krikienoid 🐛	robert-westenberger 📖 🐛	syntactic-salt 🐛