focus-trap-react
Advanced tools
Package description
The focus-trap-react package is a React wrapper for the focus-trap library, which is used to manage focus within a DOM node. This is particularly useful for accessibility purposes, ensuring that keyboard navigation is contained within a specific area, such as a modal dialog or a dropdown menu.
Basic Focus Trap
This example demonstrates a basic focus trap that contains three buttons. When the focus is within this div, it will be trapped and cannot move outside of it using keyboard navigation.
import React from 'react';
import FocusTrap from 'focus-trap-react';
const BasicFocusTrap = () => (
<FocusTrap>
<div>
<button>Button 1</button>
<button>Button 2</button>
<button>Button 3</button>
</div>
</FocusTrap>
);
export default BasicFocusTrap;Focus Trap with Initial Focus
This example shows a focus trap where the initial focus is set to a specific button using the `initialFocus` prop. When the focus trap is activated, the focus will automatically move to the button with the ID 'initial-focus'.
import React from 'react';
import FocusTrap from 'focus-trap-react';
const FocusTrapWithInitialFocus = () => (
<FocusTrap initialFocus='#initial-focus'>
<div>
<button id='initial-focus'>Initial Focus Button</button>
<button>Button 2</button>
<button>Button 3</button>
</div>
</FocusTrap>
);
export default FocusTrapWithInitialFocus;Focus Trap with Return Focus
This example demonstrates a focus trap that will return the focus to the element that activated it once the trap is deactivated. The `returnFocus` prop ensures that the focus goes back to the button that was clicked to activate the focus trap.
import React, { useState } from 'react';
import FocusTrap from 'focus-trap-react';
const FocusTrapWithReturnFocus = () => {
const [isTrapActive, setIsTrapActive] = useState(false);
return (
<div>
<button onClick={() => setIsTrapActive(true)}>Activate Focus Trap</button>
{isTrapActive && (
<FocusTrap returnFocus>
<div>
<button onClick={() => setIsTrapActive(false)}>Deactivate Focus Trap</button>
<button>Button 2</button>
<button>Button 3</button>
</div>
</FocusTrap>
)}
</div>
);
};
export default FocusTrapWithReturnFocus;react-focus-lock is another React component that provides a focus management solution. It ensures that the focus stays within a specified area, similar to focus-trap-react. However, react-focus-lock offers additional features like auto-locking and focus restoration, making it a more feature-rich alternative.
react-aria-modal is a React component for creating accessible modal dialogs. It includes focus trapping as part of its functionality, ensuring that keyboard navigation is contained within the modal. While it is more specialized for modal dialogs, it provides a robust solution for focus management within modals.
react-modal is a widely-used React component for creating modals. It includes built-in focus management to trap focus within the modal when it is open. While it is primarily focused on modal dialogs, it offers a comprehensive solution for focus trapping within modals.
Changelog
8.8.2
preventScroll option on deactivation if returning focus.Readme
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?
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.
npm install focus-trap-react
dist/focus-trap-react.js is the Babel-compiled file that you'll use.
React >= 16.0.0.
Basically IE9+.
Why? Because this module's core functionality comes from focus-trap, which uses a couple of IE9+ functions.
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'));
Type: Object, optional
Pass any of the options available in focus-trap's createOptions.
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.
Type: Boolean, optional
If you would like to pause or unpause the focus trap (see focus-trap's documentation), toggle this prop.
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).
See CONTRIBUTING.
In alphabetical order:
FAQs
Unknown package
The npm package focus-trap-react receives a total of 486,931 weekly downloads. As such, focus-trap-react popularity was classified as popular.
We found that focus-trap-react demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 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
Cyber insurance rates are dropping as the market matures, according to a new report projecting global premiums to reach $43 billion by 2030, driven by international market uptake and growth in the SME sector.
Research
Security News
Socket researchers unpack a typosquatting package with malicious code that logs keystrokes and exfiltrates sensitive data to a remote server.
Security News
The JavaScript community has launched the e18e initiative to improve ecosystem performance by cleaning up dependency trees, speeding up critical parts of the ecosystem, and documenting lighter alternatives to established tools.
