keys/hooks/use-focus-restore

useFocusRestore

standalonefocusaccessibilityoverlay

Capture and restore focus around overlays, panels, command palettes, and triggerless temporary UI with nested stack safety.

useFocusRestore captures the currently focused element before temporary UI opens and returns focus to it when that UI closes. It is standalone (no provider) and stack-aware, so nested overlays restore in close order and an older layer never steals focus from a newer one. Use it when there is no single trigger button to focus back — command palettes, globally summoned panels, and toasts-turned-dialogs.

tsx

1 const focusRestore = useFocusRestore()

When to use it

A panel or palette is opened from a keyboard shortcut rather than a specific button, so focus must return to wherever the user was.
Several temporary surfaces can stack and each must restore focus to the layer beneath it.
You need restore semantics but not Tab trapping — for trapping, use useFocusTrap (which manages restoration internally).

Installation

$pnpm exec dgadd add keys/focus-restore

[Installs to]src/hooks/use-focus-restore.ts[Item]keys/focus-restore

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

@diffgazer/keys requires no CSS or Tailwind setup.

Parameters

Name	Type	Default	Description
options.enabled	boolean	true	Whether capture and restore are active.
options.restoreOnUnmount	boolean	true	Restore focus during cleanup if capture was called and restore was not called manually.
options.preventScroll	boolean	false	Pass preventScroll to the focus call when restoring focus.
options.fallback	HTMLElement \| null	null	Fallback element to focus when the captured target is unavailable.

Returns

{ capture: (ownerDocument?: Document) => HTMLElement | null; restore: () => boolean; target: HTMLElement | null }capture stores the current focus target, restore focuses the captured or fallback target, and target exposes the last captured element.

Call capture() as the overlay opens (storing the active element) and restore() as it closes. target exposes the last captured element.

Examples

Temporary panel focus restore

Preview

tsx

1 "use client";2 3 import { useFocusRestore } from "@diffgazer/keys";4 import { useEffect, useRef, useState } from "react";5 6 export default function UseFocusRestoreBasic() {7   const [open, setOpen] = useState(false);8   const panelRef = useRef<HTMLDivElement>(null);9   const focusRestore = useFocusRestore({ restoreOnUnmount: true });10 11   useEffect(() => {12     if (open) panelRef.current?.focus();13   }, [open]);14 15   const openPanel = () => {16     focusRestore.capture();17     setOpen(true);18   };19 20   const closePanel = () => {21     setOpen(false);22     focusRestore.restore();23   };24 25   return (26     <div>27       <button type="button" onClick={openPanel}>28         Open panel29       </button>30 31       {open && (32         <div ref={panelRef} role="dialog" aria-label="Temporary panel" tabIndex={-1}>33           <p>Focus returns to the opener when this panel closes.</p>34           <button type="button" onClick={closePanel}>35             Close36           </button>37         </div>38       )}39     </div>40   );41 }42

Triggerless palette with fallback

Preview

tsx

1 "use client";2 3 import { useFocusRestore } from "@diffgazer/keys";4 import { useEffect, useRef, useState } from "react";5 6 export default function UseFocusRestoreFallback() {7   const [open, setOpen] = useState(false);8   const [anchor, setAnchor] = useState<HTMLDivElement | null>(null);9   const paletteRef = useRef<HTMLDivElement>(null);10 11   // Summon opens the palette and captures the current focus. On close, focus12   // returns there; `fallback` (the editor surface) catches the case where13   // nothing was focused at open time so focus never lands on <body>.14   const focusRestore = useFocusRestore({ fallback: anchor });15 16   useEffect(() => {17     if (open) paletteRef.current?.focus();18   }, [open]);19 20   const openPalette = () => {21     focusRestore.capture();22     setOpen(true);23   };24 25   const closePalette = () => {26     setOpen(false);27     focusRestore.restore();28   };29 30   return (31     <div>32       <div ref={setAnchor} tabIndex={-1} style={{ padding: 8, border: "1px dashed currentColor" }}>33         Editor surface (restore anchor)34       </div>35 36       <button type="button" onClick={openPalette} style={{ marginTop: 8 }}>37         Summon palette38       </button>39 40       {open && (41         <div42           ref={paletteRef}43           role="dialog"44           aria-label="Command palette"45           tabIndex={-1}46           style={{ marginTop: 8, padding: 12, border: "1px solid currentColor" }}47         >48           <p>Closing restores focus to wherever it was, or to the editor surface fallback.</p>49           <button type="button" onClick={closePalette}>50             Close51           </button>52         </div>53       )}54     </div>55   );56 }57

Notes

Hook boundary

useFocusRestore is the React hook. getRestorableFocusTarget and restoreFocus are plain DOM utilities for non-hook code.

Nested overlays

Focus restore entries are stack-aware, so nested overlays restore focus in close order and older layers do not steal focus from newer ones.

Edge cases

fallback. When nothing was focused at capture time, or the captured element is gone, focus moves to the fallback element. Supply one for triggerless UI so focus never lands on <body>.
restoreOnUnmount. On by default — if the component unmounts after capture() without an explicit restore(), cleanup restores focus. Set it to false when another hook (such as useFocusTrap) owns the restoration timing.
Stack ordering. Only the top stack entry restores. Releasing a middle entry removes it without moving focus, so nested overlays unwind correctly.
Hook vs utilities. useFocusRestore is the React hook; getRestorableFocusTarget and restoreFocus are plain DOM utilities for non-hook code.

useFocusTrap — trap Tab and restore focus on release.
Utilities — getRestorableFocusTarget and restoreFocus for imperative code.
Focus and scroll guide — overlay focus patterns.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.