Need help with focus-layers?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

discord
268 Stars 8 Forks MIT License 62 Commits 5 Opened issues

Description

Tiny React hooks for isolating focus within subsections of the DOM.

Services available

!
?

Need anything else?

Contributors list

Focus Layers

Tiny React hooks for isolating focus within subsections of the DOM. Useful for supporting accessible

dialog
widgets like modals, popouts, and alerts.

No wrapper components, no emulation, no pre-defined "list of tabbable elements", and no data attributes. Implemented entirely with native APIs and events, with no additional dependencies.

Installation

This package is published under

focus-layers
and can be installed with any npm-compatible package manager.

Basic Usage

Call

useFocusLock
inside a component and provide it a ref to the DOM node to use as the container for the focus layer. When the component mounts, it will lock focus to elements within that node, and the lock will be released when the component unmounts.
import useFocusLock from "focus-layers";

function Dialog({ children }: { children: React.ReactNode }) { const containerRef = React.useRef(); useFocusLock(containerRef);

return (

{children}
); }

function App() { const [open, setOpen] = React.useState(false);

return (

setOpen(true)}>Show Dialog {open && (

When this dialog is open, focus is trapped inside! Tabbing will always bring focus back to this button.

setOpen(false)}>Close Dialog
)}
); }

Returning Focus

After unmounting, locks will return focus to the element that was focused when the lock was mounted. This return target can also be controlled by the second parameter of

useFocusLock
.
function DialogWithExplicitReturn() {
  const [open, setOpen] = React.useState(false);

const containerRef = React.useRef(); const returnRef = React.useRef(); useFocusLock(containerRef, { returnRef });

return ( <react.fragment> Focus will be returned here setOpen(true)}>Even though this button opens the Dialog {open && (

setOpen(false)}>Close Dialog )} </react.fragment> ); }

Lock Layers

Locks Layers are quite literally layers of locks, meaning they can be stacked on top of each other to create a chain of focus traps. When the top layer unmounts, the layer below it takes over as the active lock. Layers can be removed in any order, and the top layer will always remain active.

This is useful for implementing confirmations inside of modals, or flows between multiple independent modals, where one dialog will open another, and so on.

function LayeredDialogs() {
  const [firstOpen, setFirstOpen] = React.useState(false);
  const [secondOpen, setSecondOpen] = React.useState(false);

return (

setFirstOpen(true)}>Open First Dialog

  {firstOpen &amp;&amp; (
    <dialog>
      <p>This is the first dialog that has a second confirmation after it.</p>
      <button onclick="{()"> setSecondOpen(true)}&gt;Confirm</button>
    </dialog>
  )}

  {secondOpen &amp;&amp; (
    <dialog>
      <p>This is the second dialog, opened by the first one.</p>
      <button onclick="{()"> setSecondOpen(false)}&gt;Confirm this dialog</button>
      <button onclick="{()"> {
          setSecondOpen(false);
          setFirstOpen(false);
        }}&gt;
        Close both dialogs
      </button>
    </dialog>
  )}
</div>

); }

Note that layers only track their own return targets. If multiple layers are unmounting, it is not always guaranteed that the original return target will be focused afterward. In this case, it is best to provide an explicit return target so that focus is not left ambiguous after unmounting.

Subscribing to the Lock Stack

Layers are managed by a global

LOCK_STACK
object. You can subscribe to this stack to get updates whenever any focus layers are active. This is useful for marking the rest of your app with
aria-hidden
when modals are active, or performing any other tasks on demand:
import { LOCK_STACK } from "focus-layers";

function App() { const [focusLockActive, setFocusLockActive] = React.useState(false); React.useEffect(() => { LOCK_STACK.subscribe(setFocusLockActive); return () => LOCK_STACK.unsubscribe(setFocusLockActive); }, []);

return ( <react.fragment> // This div represents your main app content

// This div would be where the dialog layers are rendered
</react.fragment> ); }

The

subscribe
and
unsubscribe
methods are useful for listening to stack changes outside of the React's rendering pipeline, but as a convenience, the
useLockSubscription
hook performs the same behavior tied to a component's lifecycle.
import { useLockSubscription } from "focus-layers";

function Component() { useLockSubscription((enabled) => console.log(focus locking is now ${enabled ? "enabled" : "disabled"}), ); }

Edge Guards

Browsers do not provide a clean way of intercepting focus events that cause focus to leave the DOM. Specifically, there is no way to directly prevent a tab/shift-tab action from moving focus out of the document and onto the browser's controls or another window.

This can cause issues with focus isolation at the edges of the DOM, where there are no more tabbable elements past the focus lock layer for focus to move to before exiting the DOM.

Semantically, this is valid behavior, but it is often nice to ensure that focus is still locked consistently. The solution is to add hidden divs with

tabindex="0"
to the beginning and end of the DOM (or around the focus layer) so that there is always another element for focus to move to while inside of a focus layer.

This library provides a

FocusGuard
component that you can render which will automatically activate when any focus layer is active, and hide itself otherwise. It renders a div that is always visually hidden, but becomes tabbable when active. These can be added at the actual edges of the DOM, or just directly surrounding any active focus layers.
import { FocusGuard } from "focus-layers";

function App() { return (

// Render the rest of your app or your modal layers here.
); }

Focus will still be trapped even without these guards in place, but the user will be able to tab out of the page and onto their browser controls if the layer is at either the very beginning or very end of the document's tab order.

Distributed Focus Groups

Layers with multiple, unconnected container nodes are not currently supported. This means layers that have content and render a React Portal as part of the layer may not allow focus to leave the layer and reach the portal.

Rendering a layer entirely within a Portal, or by any other means where there is a single containing node, is supported.

Support for groups may be added in the future to address this issue. However, it's worth noting that Portals already do not play well with tab orders and should generally not be used as anything other than an isolated focus layer. Otherwise the entire premise that focus is locked into the layer is effectively broken anyway.

External Focus Layers

The

LOCK_STACK
provides a way of integrating your own layers into the system. This can be useful when integrating with other libraries or components that implement their own focus management, or manually triggering focus locks that aren't tied to a component lifecycle.

Activating a layer is as simple as calling

add
with a
uid
and an
EnabledCallback
, which will be called when the
LOCK_STACK
determines that the layer should be active. The callback will be invoked immediately by the call to
add
, indicating that the layer is now active. The layer can then be removed at any time in the future via the
remove
method.
import { LOCK_STACK } from "focus-layers";

const enabled = false; const setEnabled = (now) => (enabled = now);

LOCK_STACK.add("custom lock", setEnabled); // Sometime later LOCK_STACK.remove("custom lock");

Integrating with the

LOCK_STACK
is a promise that your lock will enable and disable itself when it is told to (via the callback). Adding your lock to the stack is also a promise that you will remove it from the stack once the lock is "unmounted" or otherwise removed from use. Without removing your lock, all layers below your lock will be unable to regain focus.

If you are inside of a component and want to tie the focus lock to its lifecycle, you can instead use the

useLockLayer
hook to simplify adding and removing. In return it provides a boolean indicating whether the lock is currently enabled, and will force a re-render when that state changes:
import { useLockLayer } from "focus-layers";

function Component() { const enabled = useLockLayer();

React.useEffect(() => { toggleCustomLock(enabled); }, [enabled]);

return

Custom lock is {enabled ? "enabled" : "disabled"}

; }

Free Focus Layers

Custom locks can also be used to implement "free focus layers" without losing the context of the focus layers that are currently in place. Free focus is a situation where focus is not locked into any subsection and can move freely throughout the document. This can be useful for single-page applications that want to preserve focus state between multiple views where previous views get removed from the DOM while another view takes its place.

A free focus layer can easily be implemented as part of a Component. In the single-page application use case mentioned above, this might happen in the base

View
component that wraps each view.
import { useLockLayer } from "focus-layers";

function View() { useLockLayer();

return

; }

The layer gets added on mount, disabling all layers below it, and since there's no new lock to activate, the return value is just ignored, and nothing else needs to happen.

Scoped Roots

By default

useFocusLock
will attach a focus listener to the
document
itself, to capture all focus events that happen on the page. Sometimes this can have unintended consequences where a utility function wants to quickly focus an external element and perform an action. For example, cross-platform copy utilities often do this (see MDN clipboard example).

Free Focus layers would be good for this, but because these hooks are based around

useEffect
, it's likely that the current lock layer wouldn't be disabled in time for the utility to do its job. To get around this, you can scope where
useFocusLock
attaches listeners via the
attachTo
option. A good candidate for this is the node that your app is mounted to, and then have these other utilities do their work outside of that subtree.
import { useFocusLock } from "focus-layers";

function DialogWithCopyableText() { const containerRef = React.useRef(); useFocusLock(containerRef, { attachTo: document.getElementById("app-mount") || document });

const text = "this is the copied text";

return (

copy(text)}>Copy some text
); }

Alternatives

This library was created after multiple attempts at using other focus locking libraries and wanting something with a simpler implementation that leverages the browser's APIs as much as possible, and fewer implications on DOM and Component structures. There are multiple other options out there that perform a similar job in different ways, such as:

  • react-focus-lock: Lots of options, very flexible, but uses a lot of DOM nodes and attributes.
  • react-focus-trap: Nice and simple, but uses two
    div
    containers and does not work nicely with
    shift+tab
    navigation.
  • focus-trap-react: Lots of useful features, but relies on intercepting key and mouse events and querying for tabbable elements.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.