no keyboard control, everything is done watching a focus behavior, not emulating it. Focus-Locks works for all cases including positive tab indexes.
React Portals support. Even if some data is in outer space - it is still in lock.
Scattered locks, or focus lock groups - you can setup different isolated locks, and tab from one to another.
Controllable isolation level.
variable size bundle. Uses sidecar to trim UI part down to 1.5kb.
💡 focus locks is part of a bigger whole, consider scroll lock and text-to-speech lock
you have to use to really "lock" the user.
Try react-focus-on to archive everything above, assembled in the right order.
How to use
Just wrap something with focus lock, and focus will be moved inside on mount.
import FocusLock from 'react-focus-lock'; const JailForAFocus = ({onClose}) => ( <FocusLock> You can not leave this form <button onClick={onClose} /> </FocusLock> );
FocusLock would work perfectly even with no props set.
FocusLock has few props to tune behavior, all props are optional:
disabled, to disable(enable) behavior without altering the tree.
className, to set the className of the internal wrapper.
returnFocus, to return focus into initial position on unmount
By default returnFocus is disabled, so FocusLock will not restore original focus on deactivation.
This was done mostly to avoid breaking changes. We strong recommend enabling it, to provide a better user experience.
This is expected behavior for Modals, but it is better to implement it by your self. See unmounting and focus management for details
persistentFocus=false, requires any element to be focused. This also disables text selections inside, and outside focus lock.
autoFocus=true, enables or disables focusing into on Lock activation. If disabled Lock will blur an active focus.
shards=[] an array of ref pointing to the nodes, which focus lock should consider and a part of it. This is another way focus scattering.
whiteList=fn you could whitelist locations FocusLock should carry about. Everything outside it will ignore. For example - any modals.
as='div' if you need to change internal div element, to any other. Use ref forwarding to give FocusLock the node to work with.
lockProps={} to pass any extra props (except className) to the internal wrapper.
hasPositiveIndices=false to support a focus lock behavior when any elements tabIndex greater than 0.
crossFrame=true enables aggressive focus capturing within iframes
Programmatic control
Focus lock exposes a few methods to control focus programmatically.
Imperative API
useFocusInside(nodeRef) - to move focus inside the given node
useFocusScope():{autofocus, focusNext, focusPrev} - provides API to manage focus within the current lock
useFocusState() - manages focus state of a given node
useFocusController(nodeRef) - low level version of useFocusScope working without FocusLock
Declarative API
<AutoFocusInside/> - causes autofocus to look inside the component
<MoveFocusInside/> - wrapper around useFocusInside, forcibly moves focus inside on mount
<FreeFocusInside/> - hides internals from FocusLock allowing unmanaged focus
Indirect API
Focus-lock behavior can be controlled via data-attributes. Declarative API above is working by setting them for you.
See corresponding section in focus-lock for details
Focusing in OSX (Safari/Firefox) is strange!
By default tabbing in OSX sees only controls, but not links or anything else tabbable. This is system settings, and Safari/Firefox obey.
Press Option+Tab in Safari to loop across all tabbables, or change the Safari settings. There is no way to fix Firefox, unless change system settings (Control+F7). See this issue for more information.
Set up
Requirements
version 1x is React 15/16 compatible
version 2+ requires React 16.8+ (hooks)
Import
react-focus-lock exposed 3 entry points: for the classical usage, and a sidecar one.
Default usage
4kb, import FocusLock from 'react-focus-lock would give you component you are looking for.
Separated usage
Meanwhile - you dont need any focus related logic until it's needed.
Thus - you may defer that logic till Lock activation and move all related code to a sidecar.
UI, 1.5kb, import FocusLockUI from 'react-focus-lock/UI - a DOM part of a lock.
Sidecar, 3.5kb, import Sidecar from 'react-focus-lock/sidecar - which is the real focus lock.
import FocusLockUI from "react-focus-lock/UI";import {sidecar} from "use-sidecar";// prefetch sidecar. data would be loaded, but js would not be executedconst FocusLockSidecar = sidecar( () => import(/* webpackPrefetch: true */ "react-focus-lock/sidecar"));<FocusLockUI disabled={this.state.disabled} sideCar={FocusLockSidecar}> {content}</FocusLockUI>
That would split FocusLock into two pieces, reducing app size and improving the first load.
The cost of focus-lock is just 1.5kb!
Saved 3.5kb?! 🤷♂️ 3.5kb here and 3.5kb here, and your 20mb bundle is ready.
Autofocus
Use when you cannot use the native autoFocus prop - because you only want to autofocus once the Trap has been activated
prop data-autofocus on the element.
prop data-autofocus-inside on the element to focus on something inside.
AutoFocusInside component, as named export of this library.
import FocusLock, { AutoFocusInside } from 'react-focus-lock'; <FocusLock> <button>Click</button> <AutoFocusInside> <button>will be focused</button> </AutoFocusInside> </FocusLock> // is the same as <FocusLock> <button>Click</button> <button data-autofocus>will be focused</button> </FocusLock>
If there is more than one auto-focusable target - the first will be selected.
If it is a part of radio group, and rest of radio group element are also autofocusable(just put them into AutoFocusInside) -
checked one fill be selected.
AutoFocusInside will work only on Lock activation, and does nothing, then used outside of the lock.
You can use MoveFocusInside to move focus inside with or without lock.
import { MoveFocusInside } from 'react-focus-lock'; <MoveFocusInside> <button>will be focused</button> </MoveFocusInside>
Portals
Use focus scattering to handle portals
using groups. Just create a few locks (only one could be active) with a same group name
Let's take a look at the Rowing Focus as an example.
// Will set tabindex to -1 when is not focusedconst FocusTrackingButton = ({ children }) => { const { active, onFocus, ref } = useFocusState(); return ( <button tabIndex={active ? undefined : -1} onFocus={onFocus} ref={ref}> {children} </button> );};const RowingFocusInternalTrap = () => { const { autoFocus, focusNext, focusPrev } = useFocusScope(); // use useFocusController(divRef) if there is no FocusLock around useEffect(() => { autoFocus(); }, []); const onKey = (event) => { if (event.key === 'ArrowDown') { focusNext({ onlyTabbable: false }); } if (event.key === 'ArrowUp') { focusPrev({ onlyTabbable: false }); } }; return ( <div onKeyDown={onKey} // ref={divRef} for useFocusController > <FocusButton>Button1</FocusButton> <FocusButton>Button2</FocusButton> <FocusButton>Button3</FocusButton> <FocusButton>Button4</FocusButton> </div> );};// FocusLock, even disabled oneconst RowingFocusTrap = () => ( <FocusLock disabled> <RowingFocusInternalTrap /> </FocusLock>);
Guarding
As you may know - FocusLock is adding Focus Guards before and after lock to remove some side effects, like page scrolling.
But shards will not have such guards, and it might be not so cool to use them - for example if no tabbable would be
defined after shard - you will tab to the browser chrome.
You may wrap shard with InFocusGuard or just drop InFocusGuard here and there - that would solve the problem.
import {InFocusGuard} from 'react-focus-lock';// wrap with<InFocusGuard> <button /></InFocusGuard>// place before and after<InFocusGuard /><button /><InFocusGuard />
InFocusGuards would be active(tabbable) only when tabble, it protecting, is focused.
Removing Tailing Guard
If only your modal is the last tabble element on the body - you might remove the Tailing Guard,
to allow user tab into address bar.
<InFocusGuard/><button />// there is no "tailing" guard :)
Unmounting and focus management
In case FocusLock has returnFocus enabled, and it's going to be unmounted - focus will be returned after zero-timeout.
In case returnFocus is set to false, and you are going to control focus change on your own - keep in mind
React will first call Parent.componentWillUnmount, and next Child.componentWillUnmount
This means - Trap will be still active by the time you may want move(return) focus on componentWillUnmount. Please deffer this action with a zero-timeout.
Similarly, if you are using the disabled prop to control FocusLock, you will need a zero-timeout to correctly restore focus.
<FocusLock disabled={isFocusLockDisabled} onDeactivation={() => { // Without the zero-timeout, focus will likely remain on the button/control // you used to set isFocusLockDisabled = true window.setTimeout(() => myRef.current.focus(), 0); }>
Return focus to another node
In some cases the original node that was focused before the lock was activated is not the desired node to return focus to.
Some times this node might not exists at all.
first of all, FocusLock need a moment to record this node, please do not hide it onClick, but hide onBlur (Dropdown, looking at you)
second, you may specify a callback as returnFocus, letting you decide where to return focus to.
<FocusLock returnFocus={(suggestedNode) => { // somehow activeElement should not be changed if(document.activeElement.hasAttributes('main-content')) { // opt out from default behavior return false; } if (someCondition(suggestedNode)) { // proceed with the suggested node return true; } // handle return focus manually document.getElementById('the-button').focus(); // opt out from default behavior return false; }}/>
To return focus, but without jumpy page scroll returning a focus you might specify a focus option
<FocusLock returnFocus={{ preventScroll: false }} // working not in all browsers>
Not supported by Edge and Safari.
Focus fighting
Two different focus-lock-managers or even different version of a single one, being active
simultaneously will FIGHT for the focus. This usually totally breaks user experience.
React-Focus-Lock will automatically surrender, letting another library to take the lead.
Resolving focus fighting
You may wrap some render branch with FreeFocusInside, and react-focus-lock will ignore
any focus inside marked node. So in case focus moves to uncontrolled location focus-lock will not trigger letting another library to act without interference in that another location.
import { FreeFocusInside } from 'react-focus-lock';<FreeFocusInside> <div id="portal-for-modals"> in this div i am going to portal my modals, dont fight with them please </div></FreeFocusInside>
Another option for hybrid applications is to whiteList area where Focus-Lock should act, automatically allowing other managers in other areas.
The code below will scope Focus-Lock on inside the (react)root element, so anything jQuery can add to the body will be ignored.