keys/hooks/use-scope

useScope

provider-dependentscope

Push a named scope onto the keyboard scope stack. Declarative scopes follow React tree order, so nested overlays can capture shortcuts until they unmount. Auto-pops on unmount.

useScope declares a keyboard scope for the part of the tree it lives in. While the scope is active, shortcuts registered under it (useKey with scope, or useScopedNavigation) win over shortcuts owned by shallower scopes. The scope is pushed on mount and popped automatically on unmount, so layered overlays capture keys for exactly as long as they are open.

tsx

1 useScope("modal")

When to use it

A dialog, drawer, or popover should claim Escape (or arrow keys) while open, shadowing a page-level binding for the same combo.
Several overlays can stack and each deeper one should take priority until it closes.
A region needs to register provider shortcuts under a stable, named scope.

Scopes describe priority, not focus containment. To restrict a shortcut to a DOM subtree, use containerRef + focusWithinOnly on useKey. The two compose. For the full model see the scopes guide.

Installation

Requires KeyboardProvider and the @diffgazer/keys package, which is not public on npm yet.

Diffgazer packages are not yet published to npm. Until the first release, pack @diffgazer/ui and @diffgazer/keys from the repository and install those tarballs.

@diffgazer/keys requires no CSS or Tailwind setup.

Parameters

Name	Type	Default	Description
namerequired	string \| null	—	Unique name for the scope pushed onto the stack. Pass null to skip pushing without violating Hook call order.
options.enabled	boolean	true	Whether the scope is active. When false the scope is not pushed.

Returns

string | nullThe active scope name when enabled and non-null, otherwise null.

Pass the returned value as the scope option to useKey so a binding registers under this scope.

Examples

Basic scope usage

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useKey, useScope } from "@diffgazer/keys";4 import { useState } from "react";5 6 function App() {7   const [modalOpen, setModalOpen] = useState(false);8 9   useKey("ctrl+k", () => setModalOpen(true), { preventDefault: true });10 11   return (12     <div>13       <p>Press Ctrl+K to open the modal. The "ctrl+k" binding lives in the global scope.</p>14       {modalOpen && <Modal onClose={() => setModalOpen(false)} />}15     </div>16   );17 }18 19 function Modal({ onClose }: { onClose: () => void }) {20   const scope = useScope("modal");21   useKey("Escape", onClose, { scope });22 23   return (24     <div25       role="dialog"26       aria-label="Modal"27       style={{ marginTop: 8, padding: 12, border: "1px solid currentColor" }}28     >29       <p>Modal scope is active: Esc closes, Ctrl+K is suppressed.</p>30       <button type="button" onClick={onClose}>31         Close32       </button>33     </div>34   );35 }36 37 export default function UseScopeBasic() {38   return (39     <KeyboardProvider>40       <App />41     </KeyboardProvider>42   );43 }44

Nested scopes resolve deepest-first

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useKey, useScope } from "@diffgazer/keys";4 import { useState } from "react";5 6 function Page() {7   const [log, setLog] = useState("page");8   const [drawerOpen, setDrawerOpen] = useState(false);9 10   // Lives in the global scope; fires only while no deeper scope is active.11   useKey("Escape", () => setLog("page Escape"));12 13   return (14     <div>15       <p>Escape here logs from the page. Open the drawer to see a deeper scope win.</p>16       <button type="button" onClick={() => setDrawerOpen((open) => !open)}>17         {drawerOpen ? "Close drawer" : "Open drawer"}18       </button>19       {drawerOpen && <Drawer setLog={setLog} />}20       <p>Last handler: {log}</p>21     </div>22   );23 }24 25 function Drawer({ setLog }: { setLog: (v: string) => void }) {26   const [dialogOpen, setDialogOpen] = useState(false);27   const scope = useScope("drawer");28 29   useKey("Escape", () => setLog("drawer Escape"), { scope });30 31   return (32     <div style={{ marginTop: 8, padding: 12, border: "1px solid currentColor" }}>33       <p>Drawer scope active. Escape logs from the drawer, not the page.</p>34       <button type="button" onClick={() => setDialogOpen(true)}>35         Open dialog36       </button>37       {dialogOpen && <Dialog onClose={() => setDialogOpen(false)} setLog={setLog} />}38     </div>39   );40 }41 42 function Dialog({ onClose, setLog }: { onClose: () => void; setLog: (v: string) => void }) {43   const scope = useScope("dialog");44 45   // Deepest scope: Escape resolves here, shadowing drawer and page.46   useKey(47     "Escape",48     () => {49       setLog("dialog Escape");50       onClose();51     },52     { scope },53   );54 55   return (56     <div57       role="dialog"58       aria-label="Dialog"59       style={{ marginTop: 8, padding: 12, border: "1px solid currentColor" }}60     >61       <p>Dialog scope is deepest. Escape closes the dialog and yields back to the drawer.</p>62       <button type="button" onClick={onClose}>63         Close64       </button>65     </div>66   );67 }68 69 export default function UseScopeNested() {70   return (71     <KeyboardProvider>72       <Page />73     </KeyboardProvider>74   );75 }76

Notes

Scope stack lifecycle

The scope is pushed when the component mounts (or when enabled becomes true and name is non-null) and automatically popped when the component unmounts, when enabled becomes false, or when name becomes null.

Active scope ordering

Declarative scopes pushed by useScope are ordered by their React-generated component identity, which keeps siblings and nested overlays deterministic across a single commit. Imperative pushScope calls are ordered above declarative scopes until popped.

Requires KeyboardProvider

useScope is a provider-dependent hook. It must be used within a <KeyboardProvider> tree.

Edge cases

name: null. Pass null to skip pushing a scope while keeping the Hook call — the supported way to make a scope conditional without breaking the Rules of Hooks.
Ordering across a commit. Declarative scopes are ordered by React component identity, keeping siblings and nested overlays deterministic within a single commit. Imperative pushScope calls from the provider sit above declarative scopes until popped.
Requires a provider. useScope reads the registry context and must live inside a KeyboardProvider tree.

useKey — register a shortcut under the scope this hook returns.
KeyboardProvider — owns the scope stack and key dispatch.
Scopes guide — stacking, priority, and imperative pushes.

Source

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