keys/hooks/use-key

useKey

provider-dependenthotkeykeyboard

Bind keyboard shortcuts to handlers with scoped, document-level, or container-scoped listening. Supports single key, array of keys, or key map overloads.

useKey is the core binding primitive of @diffgazer/keys. It registers one or more hotkeys with the nearest KeyboardProvider and runs your handler when a matching combo fires. Bindings are scope-aware: the provider resolves which handler wins when several match, and a binding is automatically removed when its component unmounts.

tsx

1 useKey("Escape", () => setOpen(false))

When to use it

Application shortcuts — Cmd+K to open a palette, Escape to close an overlay, ? to show help.
Component shortcuts that should only fire while a region has focus (pass containerRef + focusWithinOnly).
Layered UI where a deeper surface (dialog, drawer) should shadow a shortcut owned by the page underneath — combine with useScope.

Higher-level navigation hooks (useScopedNavigation, useFocusZone, useActionRowNavigation) are built on useKey; reach for it directly when you need an individual shortcut rather than list or zone movement.

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
hotkeyrequired	string \| readonly string[] \| Record<string, KeyHandler>	—	A single key combo, an array of key combos, or a map of key combos to handlers.
handler	KeyHandler	—	Callback invoked when the hotkey fires. Not used with the key-map overload.
options.enabled	boolean	true	Whether the binding is active.
options.scope	string \| null	—	Explicit keyboard scope to register the binding under. Pass null to skip registration. Defaults to the nearest active KeyboardProvider scope for this hook's declaration order.
options.allowInInput	boolean	false	Allow the hotkey to fire when an input, textarea, or contenteditable element is focused.
options.containerRef	RefObject<HTMLElement \| null>	—	DOM boundary used by focusWithinOnly to restrict when the handler fires.
options.focusWithinOnly	boolean	false	Only fire the handler when focus is within the container element.
options.preventDefault	boolean	false	Call preventDefault() on the keyboard event when the hotkey matches.

The hotkey string uses the hotkey format: a key name with optional ctrl+, meta+, alt+, and shift+ modifiers (for example "meta+k", "shift+?", "Escape").

Returns

voidThis hook does not return a value.

Behavior

Concern	Behavior
Editable targets	Ignored by default. A shortcut does not fire while a text-like `input`, a `textarea`, or an editable content element is focused unless `allowInInput` is set. Non-text controls such as `select`, checkbox, radio, range, and button inputs are allowed by default.
Focus scoping	With `containerRef` + `focusWithinOnly`, the handler only runs while focus is inside the container.
Scope resolution	When several bindings match the same combo, the handler in the deepest active scope runs first.
Declining	Return exactly `false` from a handler to fall through to the next lower-priority handler for that combo. Any other return value consumes the event.
`preventDefault`	When enabled, the browser default is prevented after a handler accepts. A handler that returns `false` leaves the default available unless a later matching handler accepts and prevents it.
Cleanup	Bindings are removed on unmount, when `enabled` is `false`, or when `scope` is `null`.

Examples

Basic hotkey binding

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useKey } from "@diffgazer/keys";4 import { useState } from "react";5 6 function Counter() {7   const [count, setCount] = useState(0);8 9   useKey("ArrowUp", () => setCount((c) => c + 1));10   useKey("ArrowDown", () => setCount((c) => c - 1));11   useKey("Escape", () => setCount(0));12 13   return (14     <div>15       <p style={{ fontSize: 24, fontFamily: "ui-monospace, monospace", textAlign: "center" }}>16         {count}17       </p>18       <p>ArrowUp increments, ArrowDown decrements, Escape resets.</p>19     </div>20   );21 }22 23 export default function UseKeyBasic() {24   return (25     <KeyboardProvider>26       <Counter />27     </KeyboardProvider>28   );29 }30

Key map with multiple bindings

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useKey } from "@diffgazer/keys";4 import { useState } from "react";5 6 function TextFormatter() {7   const [style, setStyle] = useState<"normal" | "bold" | "italic" | "underline">("normal");8 9   useKey(10     {11       "ctrl+b": () => setStyle("bold"),12       "ctrl+i": () => setStyle("italic"),13       "ctrl+u": () => setStyle("underline"),14       Escape: () => setStyle("normal"),15     },16     { preventDefault: true },17   );18 19   return (20     <div>21       <p22         style={{23           fontWeight: style === "bold" ? 700 : 400,24           fontStyle: style === "italic" ? "italic" : "normal",25           textDecoration: style === "underline" ? "underline" : "none",26         }}27       >28         The quick brown fox jumps over the lazy dog.29       </p>30       <p>Active: {style}</p>31       <p>Ctrl+B bold, Ctrl+I italic, Ctrl+U underline, Esc reset.</p>32     </div>33   );34 }35 36 export default function UseKeyMap() {37   return (38     <KeyboardProvider>39       <TextFormatter />40     </KeyboardProvider>41   );42 }43

Container-scoped shortcut

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useKey } from "@diffgazer/keys";4 import { useRef, useState } from "react";5 6 function Editor() {7   const [saved, setSaved] = useState(0);8   const cardRef = useRef<HTMLDivElement>(null);9 10   // focusWithinOnly + containerRef: the shortcut only fires while focus is11   // inside this card, so two editors on one page do not collide.12   useKey("ctrl+s", () => setSaved((n) => n + 1), {13     containerRef: cardRef,14     focusWithinOnly: true,15     preventDefault: true,16     allowInInput: true,17   });18 19   return (20     <div ref={cardRef} style={{ padding: 12, border: "1px solid currentColor" }}>21       <p>Click into the textarea, then press Ctrl+S. Saves: {saved}</p>22       <textarea23         aria-label="Note"24         rows={2}25         style={{ width: "100%" }}26         defaultValue="Focus me, then Ctrl+S"27       />28     </div>29   );30 }31 32 export default function UseKeyScoped() {33   return (34     <KeyboardProvider>35       <div style={{ display: "grid", gap: 8 }}>36         <Editor />37         <Editor />38         <p>Each card owns its own Ctrl+S; the binding is inert unless its card has focus.</p>39       </div>40     </KeyboardProvider>41   );42 }43

Notes

Three overloads

useKey supports three call signatures: single key + handler, array of keys + handler, and a Record<string, KeyHandler> map (no separate handler argument).

Provider-dependent

useKey registers handlers when a KeyboardProvider is present. Without a provider it is a no-op.

Scope-aware

Handlers respect the scope stack managed by useScope. Deeper scopes take priority over shallower ones.

Declining a match

Return exactly false from a handler to let the next lower-priority matching handler in the active scope run. Other return values are ignored. When a handler with preventDefault enabled accepts the match (returns anything other than false), event.preventDefault() runs after that handler returns. A declining handler never prevents the default.

Edge cases

No provider. Without a KeyboardProvider ancestor, useKey is a no-op — it never throws, so a copied component degrades to "no shortcut" rather than crashing.
scope: null. Passing null skips registration entirely while keeping the Hook call in place, which is the supported way to disable a binding conditionally without violating the Rules of Hooks.
Key map overload. useKey({ "ctrl+b": ..., Escape: ... }) registers several combos at once; do not pass a separate handler argument with this form.

useScope — push a named scope so deeper surfaces shadow page-level shortcuts.
KeyboardProvider — the context that dispatches matched keys.
Hotkey format — modifier and key-name reference.

Source

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

useKey

When to use it

Installation

Parameters

Returns

Behavior

Examples

Basic hotkey binding

Key map with multiple bindings

Container-scoped shortcut

Notes

Three overloads

Provider-dependent

Scope-aware

Declining a match

Edge cases

Related

Source

View hook source