README
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
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.0.0.
Browser Support
Basically IE9+.
Why? Because this module's core functionality comes from focus-trap, which uses a couple of IE9+ functions.
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');
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'));
Props
focusTrapOptions
Type: Object, optional
Pass any of the options available in focus-trap's createOptions.
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 passed in, 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 when the prop is specified, even if the prop is[](an empty array). Also note that if the refs you're putting into the array likecontainerElements={[ref1.current, ref2.current]}and one or both refs aren't resolved yet, resulting in[null, null]for example, the trap will not get created. The array must contain at least oneHTMLElementin order for the trap to get 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).
Contributing
See CONTRIBUTING.
Contributors
In alphabetical order:
