focus-trap-react is a React component that wraps the `focus-trap` library, providing an accessible way to trap focus within a DOM element. This is crucial for UI patterns like modals, dialogs, and overlays, ensuring keyboard users cannot tab outside the active component. The current stable version is 12.0.0. The library maintains a steady release cadence, typically releasing new patch versions to update its underlying `focus-trap` dependency, and major versions coinciding with significant updates to `focus-trap` or React compatibility requirements. Its key differentiator is its direct integration with React's component lifecycle, abstracting the imperative `focus-trap` API into declarative props, simplifying its use in React applications for enhanced accessibility.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Since v11.0.1, the named export `FocusTrap` is preferred. The default export is deprecated and will be removed.
import { FocusTrap } from 'focus-trap-react';
The default export for `FocusTrap` is deprecated since v11.0.1 and will be removed in a future major version. Prefer the named export.
import FocusTrap from 'focus-trap-react';
Import type definitions explicitly for TypeScript to avoid runtime overhead.
import type { FocusTrapProps } from 'focus-trap-react';
This quickstart demonstrates how to create a basic accessible modal using `FocusTrap`. It shows conditional rendering, custom `focusTrapOptions` for deactivation and initial focus, and proper ARIA attributes.
import React, { useState, useRef, useEffect } from 'react';
import { FocusTrap } from 'focus-trap-react';
const Modal = ({ onClose }) => {
const trapRef = useRef(null);
useEffect(() => {
// Optional: Log when the trap is activated/deactivated
console.log('Focus trap mounted');
return () => console.log('Focus trap unmounted');
}, []);
return (
<FocusTrap
active={true}
focusTrapOptions={{
onDeactivate: onClose,
clickOutsideDeactivates: true,
initialFocus: '#close-button',
fallbackFocus: '#close-button'
}}
_ref={trapRef}
>
<div
style={{
position: 'fixed',
top: '50%',
left: '50%',
transform: 'translate(-50%, -50%)',
backgroundColor: 'white',
padding: '20px',
border: '1px solid gray',
zIndex: 1000
}}
aria-modal="true"
role="dialog"
>
<h2>Accessible Modal Dialog</h2>
<p>This is content inside the focus trap. You cannot tab outside this box.</p>
<input type="text" placeholder="Enter something" />
<button id="close-button" onClick={onClose}>Close Modal</button>
<button>Another button</button>
</div>
</FocusTrap>
);
};
const App = () => {
const [isModalOpen, setIsModalOpen] = useState(false);
return (
<div>
<h1>Focus Trap React Demo</h1>
<button onClick={() => setIsModalOpen(true)}>Open Modal</button>
{isModalOpen && <Modal onClose={() => setIsModalOpen(false)} />}
<p>Content behind the modal.</p>
<input type="text" placeholder="Outside input" />
</div>
);
};
export default App;
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.