focus-layers - GitLite

KO | EN

gitlite — search

#react #llm #go #android #machine-learning #rust #linux #macos #awesome #cli #kubernetes #awesome-list #security #ios

focus-layers

(★ 302)

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

File Explorer

Download Latest Version (.zip)

- AutoFocusExample.tsx
- CustomLockExample.tsx
- Dialog.tsx
- ExplicitReturnExample.tsx
- FreeFocusToggleExample.tsx
- index.html
- index.tsx
- LayeringExample.tsx
- README.md
- SimpleExample.tsx
- SubscriptionExample.tsx
- - wrapFocus.tsx
- LockStack.tsx
- useFocusLock.tsx
.gitignore
.prettierrc
LICENSE
package.json
README.md
tsconfig.json
yarn.lock

# Installation Guide

1. Get the code

git clone https://github.com/discord/focus-layers

Downloads the entire project code from GitHub to your computer.

cd focus-layers

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install

Downloads and installs the libraries listed in package.json.

npm start

Starts the development/run server.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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`](https://www.npmjs.com/package/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.

```tsx
import useFocusLock from "focus-layers";

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

return (
    <div ref={containerRef} tabIndex={-1}>
      {children}
    </div>
  );
}

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

return (
    <div>
      <button onClick={() => setOpen(true)}>Show Dialog</button>
      {open && (
        <Dialog>
          <p>
            When this dialog is open, focus is trapped inside! Tabbing will always bring focus back
            to this button.
          </p>
          <button onClick={() => setOpen(false)}>Close Dialog</button>
        </Dialog>
      )}
    </div>
  );
}
```

## 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`.

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

const containerRef = React.useRef<HTMLDivElement>();
  const returnRef = React.useRef<HTMLButtonElement>();
  useFocusLock(containerRef, { returnRef });

return (
    <React.Fragment>
      <button ref={returnRef}>Focus will be returned here</button>
      <button onClick={() => setOpen(true)}>Even though this button opens the Dialog</button>
      {open && (
        <Dialog>
          <button onClick={() => setOpen(false)}>Close Dialog</button>
        </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.

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

return (
    <div>
      <button onClick={() => setFirstOpen(true)}>Open First Dialog</button>

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

{secondOpen && (
        <Dialog>
          <p>This is the second dialog, opened by the first one.</p>
          <button onClick={() => setSecondOpen(false)}>Confirm this dialog</button>
          <button
            onClick={() => {
              setSecondOpen(false);
              setFirstOpen(false);
            }}>
            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:

```tsx
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
      <div aria-hidden={focusLockActive} />
      // This div would be where the dialog layers are rendered
      <div />
    </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.

```tsx
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.

```tsx
import { FocusGuard } from "focus-layers";

function App() {
  return (
    <div id="app-root">
      <FocusGuard />
      // Render the rest of your app or your modal layers here.
      <FocusGuard />
    </div>
  );
}
```

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.

```typescript
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:

```tsx
import { useLockLayer } from "focus-layers";

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

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

return <p>Custom lock is {enabled ? "enabled" : "disabled"}</p>;
}
```

## 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.

```tsx
import { useLockLayer } from "focus-layers";

function View() {
  useLockLayer();

return <div />;
}
```

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](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard#Writing_to_the_clipboard)).

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.

```tsx
import { useFocusLock } from "focus-layers";

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

const text = "this is the copied text";

return (
    <div containerRef={containerRef}>
      <button onClick={() => copy(text)}>Copy some text</button>
    </div>
  );
}
```

## 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](https://github.com/theKashey/react-focus-lock): Lots of options, very flexible,
  but uses a lot of DOM nodes and attributes.
- [react-focus-trap](https://github.com/vigetlabs/react-focus-trap): Nice and simple, but uses two
  `div` containers and does not work nicely with `shift+tab` navigation.
- [focus-trap-react](https://github.com/davidtheclark/focus-trap-react): Lots of useful features,
  but relies on intercepting key and mouse events and querying for tabbable elements.