@tanstack/react-hotkeys 0.6.0 → 0.7.0

package/dist/useHotkeySequences.d.cts

@@ -0,0 +1,63 @@
+import { UseHotkeySequenceOptions } from "./useHotkeySequence.cjs";
+import { HotkeyCallback, HotkeySequence } from "@tanstack/hotkeys";
+
+//#region src/useHotkeySequences.d.ts
+/**
+ * A single sequence definition for use with `useHotkeySequences`.
+ */
+interface UseHotkeySequenceDefinition {
+  /** Array of hotkey strings that form the sequence */
+  sequence: HotkeySequence;
+  /** The function to call when the sequence is completed */
+  callback: HotkeyCallback;
+  /** Per-sequence options (merged on top of commonOptions) */
+  options?: UseHotkeySequenceOptions;
+}
+/**
+ * React hook for registering multiple keyboard shortcut sequences at once (Vim-style).
+ *
+ * Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
+ * register variable-length lists without violating the rules of hooks.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * Definitions with an empty `sequence` are skipped (no registration).
+ *
+ * @param definitions - Array of sequence definitions to register
+ * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
+ *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+ *   via `setOptions` (no unregister/re-register churn).
+ *
+ * @example
+ * ```tsx
+ * function VimPalette() {
+ *   useHotkeySequences([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function DynamicSequences({ items }) {
+ *   useHotkeySequences(
+ *     items.map((item) => ({
+ *       sequence: item.chords,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+declare function useHotkeySequences(definitions: Array<UseHotkeySequenceDefinition>, commonOptions?: UseHotkeySequenceOptions): void;
+//#endregion
+export { UseHotkeySequenceDefinition, useHotkeySequences };
+//# sourceMappingURL=useHotkeySequences.d.cts.map

package/dist/useHotkeySequences.d.ts

@@ -0,0 +1,63 @@
+import { UseHotkeySequenceOptions } from "./useHotkeySequence.js";
+import { HotkeyCallback, HotkeySequence } from "@tanstack/hotkeys";
+
+//#region src/useHotkeySequences.d.ts
+/**
+ * A single sequence definition for use with `useHotkeySequences`.
+ */
+interface UseHotkeySequenceDefinition {
+  /** Array of hotkey strings that form the sequence */
+  sequence: HotkeySequence;
+  /** The function to call when the sequence is completed */
+  callback: HotkeyCallback;
+  /** Per-sequence options (merged on top of commonOptions) */
+  options?: UseHotkeySequenceOptions;
+}
+/**
+ * React hook for registering multiple keyboard shortcut sequences at once (Vim-style).
+ *
+ * Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
+ * register variable-length lists without violating the rules of hooks.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * Definitions with an empty `sequence` are skipped (no registration).
+ *
+ * @param definitions - Array of sequence definitions to register
+ * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
+ *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+ *   via `setOptions` (no unregister/re-register churn).
+ *
+ * @example
+ * ```tsx
+ * function VimPalette() {
+ *   useHotkeySequences([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function DynamicSequences({ items }) {
+ *   useHotkeySequences(
+ *     items.map((item) => ({
+ *       sequence: item.chords,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+declare function useHotkeySequences(definitions: Array<UseHotkeySequenceDefinition>, commonOptions?: UseHotkeySequenceOptions): void;
+//#endregion
+export { UseHotkeySequenceDefinition, useHotkeySequences };
+//# sourceMappingURL=useHotkeySequences.d.ts.map

package/dist/useHotkeySequences.js

@@ -0,0 +1,138 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { isRef } from "./utils.js";
+import { formatHotkeySequence, getSequenceManager } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "react";
+
+//#region src/useHotkeySequences.ts
+/**
+* React hook for registering multiple keyboard shortcut sequences at once (Vim-style).
+*
+* Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
+* register variable-length lists without violating the rules of hooks.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* Callbacks and options are synced on every render to avoid stale closures.
+*
+* Definitions with an empty `sequence` are skipped (no registration).
+*
+* @param definitions - Array of sequence definitions to register
+* @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
+*   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
+*   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+*   via `setOptions` (no unregister/re-register churn).
+*
+* @example
+* ```tsx
+* function VimPalette() {
+*   useHotkeySequences([
+*     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+*     { sequence: ['D', 'D'], callback: () => deleteLine() },
+*     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
+*   ])
+* }
+* ```
+*
+* @example
+* ```tsx
+* function DynamicSequences({ items }) {
+*   useHotkeySequences(
+*     items.map((item) => ({
+*       sequence: item.chords,
+*       callback: item.action,
+*       options: { enabled: item.enabled },
+*     })),
+*     { preventDefault: true },
+*   )
+* }
+* ```
+*/
+function useHotkeySequences(definitions, commonOptions = {}) {
+	const defaultOptions = useDefaultHotkeysOptions().hotkeySequence;
+	const manager = getSequenceManager();
+	const registrationsRef = useRef(/* @__PURE__ */ new Map());
+	const definitionsRef = useRef(definitions);
+	const sequenceStringsRef = useRef([]);
+	const commonOptionsRef = useRef(commonOptions);
+	const defaultOptionsRef = useRef(defaultOptions);
+	const managerRef = useRef(manager);
+	const sequenceStrings = definitions.map((def) => formatHotkeySequence(def.sequence));
+	definitionsRef.current = definitions;
+	sequenceStringsRef.current = sequenceStrings;
+	commonOptionsRef.current = commonOptions;
+	defaultOptionsRef.current = defaultOptions;
+	managerRef.current = manager;
+	useEffect(() => {
+		const prevRegistrations = registrationsRef.current;
+		const nextRegistrations = /* @__PURE__ */ new Map();
+		const rows = [];
+		for (let i = 0; i < definitionsRef.current.length; i++) {
+			const def = definitionsRef.current[i];
+			const seqStr = sequenceStringsRef.current[i];
+			const seq = def.sequence;
+			if (seq.length === 0) continue;
+			const mergedOptions = {
+				...defaultOptionsRef.current,
+				...commonOptionsRef.current,
+				...def.options
+			};
+			const resolvedTarget = isRef(mergedOptions.target) ? mergedOptions.target.current : mergedOptions.target ?? (typeof document !== "undefined" ? document : null);
+			if (!resolvedTarget) continue;
+			const registrationKey = `${i}:${seqStr}`;
+			rows.push({
+				registrationKey,
+				def,
+				seq,
+				seqStr,
+				mergedOptions,
+				resolvedTarget
+			});
+		}
+		const nextKeys = new Set(rows.map((r) => r.registrationKey));
+		for (const [key, record] of prevRegistrations) if (!nextKeys.has(key) && record.handle.isActive) record.handle.unregister();
+		for (const row of rows) {
+			const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row;
+			const existing = prevRegistrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				nextRegistrations.set(registrationKey, existing);
+				continue;
+			}
+			if (existing?.handle.isActive) existing.handle.unregister();
+			const handle = managerRef.current.register(seq, def.callback, {
+				...mergedOptions,
+				target: resolvedTarget
+			});
+			nextRegistrations.set(registrationKey, {
+				handle,
+				target: resolvedTarget
+			});
+		}
+		registrationsRef.current = nextRegistrations;
+	});
+	useEffect(() => {
+		return () => {
+			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
+			registrationsRef.current = /* @__PURE__ */ new Map();
+		};
+	}, []);
+	for (let i = 0; i < definitions.length; i++) {
+		const def = definitions[i];
+		const seqStr = sequenceStrings[i];
+		const registrationKey = `${i}:${seqStr}`;
+		const handle = registrationsRef.current.get(registrationKey)?.handle;
+		if (handle?.isActive && def.sequence.length > 0) {
+			handle.callback = def.callback;
+			const { target: _target, ...optionsWithoutTarget } = {
+				...defaultOptions,
+				...commonOptions,
+				...def.options
+			};
+			handle.setOptions(optionsWithoutTarget);
+		}
+	}
+}
+
+//#endregion
+export { useHotkeySequences };
+//# sourceMappingURL=useHotkeySequences.js.map

package/dist/useHotkeySequences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeySequences.js","names":[],"sources":["../src/useHotkeySequences.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeySequenceOptions } from './useHotkeySequence'\nimport type {\n  HotkeyCallback,\n  HotkeySequence,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\n/**\n * A single sequence definition for use with `useHotkeySequences`.\n */\nexport interface UseHotkeySequenceDefinition {\n  /** Array of hotkey strings that form the sequence */\n  sequence: HotkeySequence\n  /** The function to call when the sequence is completed */\n  callback: HotkeyCallback\n  /** Per-sequence options (merged on top of commonOptions) */\n  options?: UseHotkeySequenceOptions\n}\n\n/**\n * React hook for registering multiple keyboard shortcut sequences at once (Vim-style).\n *\n * Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can\n * register variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * Definitions with an empty `sequence` are skipped (no registration).\n *\n * @param definitions - Array of sequence definitions to register\n * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).\n *   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row\n *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle\n *   via `setOptions` (no unregister/re-register churn).\n *\n * @example\n * ```tsx\n * function VimPalette() {\n *   useHotkeySequences([\n *     { sequence: ['G', 'G'], callback: () => scrollToTop() },\n *     { sequence: ['D', 'D'], callback: () => deleteLine() },\n *     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function DynamicSequences({ items }) {\n *   useHotkeySequences(\n *     items.map((item) => ({\n *       sequence: item.chords,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeySequences(\n  definitions: Array<UseHotkeySequenceDefinition>,\n  commonOptions: UseHotkeySequenceOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: SequenceRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkeySequence\n  const manager = getSequenceManager()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const definitionsRef = useRef(definitions)\n  const sequenceStringsRef = useRef<Array<string>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const sequenceStrings = definitions.map((def) =>\n    formatHotkeySequence(def.sequence),\n  )\n\n  definitionsRef.current = definitions\n  sequenceStringsRef.current = sequenceStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof definitionsRef.current)[number]\n      seq: HotkeySequence\n      seqStr: string\n      mergedOptions: UseHotkeySequenceOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < definitionsRef.current.length; i++) {\n      const def = definitionsRef.current[i]!\n      const seqStr = sequenceStringsRef.current[i]!\n      const seq = def.sequence\n      if (seq.length === 0) {\n        continue\n      }\n\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeySequenceOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${seqStr}`\n      rows.push({\n        registrationKey,\n        def,\n        seq,\n        seqStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(seq, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n  })\n\n  useEffect(() => {\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [])\n\n  for (let i = 0; i < definitions.length; i++) {\n    const def = definitions[i]!\n    const seqStr = sequenceStrings[i]!\n    const registrationKey = `${i}:${seqStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive && def.sequence.length > 0) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeySequenceOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,SAAgB,mBACd,aACA,gBAA0C,EAAE,EACtC;CAMN,MAAM,iBAAiB,0BAA0B,CAAC;CAClD,MAAM,UAAU,oBAAoB;CAEpC,MAAM,mBAAmB,uBAAwC,IAAI,KAAK,CAAC;CAC3E,MAAM,iBAAiB,OAAO,YAAY;CAC1C,MAAM,qBAAqB,OAAsB,EAAE,CAAC;CACpD,MAAM,mBAAmB,OAAO,cAAc;CAC9C,MAAM,oBAAoB,OAAO,eAAe;CAChD,MAAM,aAAa,OAAO,QAAQ;CAElC,MAAM,kBAAkB,YAAY,KAAK,QACvC,qBAAqB,IAAI,SAAS,CACnC;AAED,gBAAe,UAAU;AACzB,oBAAmB,UAAU;AAC7B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,iBAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAOD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,eAAe,QAAQ,QAAQ,KAAK;GACtD,MAAM,MAAM,eAAe,QAAQ;GACnC,MAAM,SAAS,mBAAmB,QAAQ;GAC1C,MAAM,MAAM,IAAI;AAChB,OAAI,IAAI,WAAW,EACjB;GAGF,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiB,MAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,KAAK,eAAe,mBAAmB;GAErE,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AACnE,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,KAAK,IAAI,UAAU;IAC5D,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;GAC3B;AAEF,iBAAgB;AACd,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,EAAE,CAAC;AAEN,MAAK,IAAI,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;EAC3C,MAAM,MAAM,YAAY;EACxB,MAAM,SAAS,gBAAgB;EAC/B,MAAM,kBAAkB,GAAG,EAAE,GAAG;EAChC,MAAM,SAAS,iBAAiB,QAAQ,IAAI,gBAAgB,EAAE;AAE9D,MAAI,QAAQ,YAAY,IAAI,SAAS,SAAS,GAAG;AAC/C,UAAO,WAAW,IAAI;GAMtB,MAAM,EAAE,QAAQ,SAAS,GAAG,yBALN;IACpB,GAAG;IACH,GAAG;IACH,GAAG,IAAI;IACR;AAED,UAAO,WAAW,qBAAqB"}

package/dist/useHotkeys.cjs

@@ -18,7 +18,10 @@ let react = require("react");
 * Callbacks and options are synced on every render to avoid stale closures.
 *
 * @param hotkeys - Array of hotkey definitions to register
-* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
+*   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row
+*   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+*   via `setOptions` (no unregister/re-register churn).
 *
 * @example
 * ```tsx
@@ -105,17 +108,13 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			});
 		}
 		registrationsRef.current = nextRegistrations;
+	});
+	(0, react.useEffect)(() => {
 		return () => {
 			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
 			registrationsRef.current = /* @__PURE__ */ new Map();
 		};
-	}, [hotkeyStrings.join("\0"), hotkeys.map((def) => {
-		return {
-			...defaultOptions,
-			...commonOptions,
-			...def.options
-		}.enabled ?? true;
-	}).join("\0")]);
+	}, []);
 	for (let i = 0; i < hotkeys.length; i++) {
 		const def = hotkeys[i];
 		const hotkeyStr = hotkeyStrings[i];

package/dist/useHotkeys.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeys.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * React hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    typeof def.hotkey === 'string'\n      ? def.hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  // Stable serialized keys for effect dependencies\n  const hotkeyKey = hotkeyStrings.join('\\0')\n  const enabledKey = hotkeys\n    .map((def) => {\n      const merged = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      }\n      return merged.enabled ?? true\n    })\n    .join('\\0')\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [hotkeyKey, enabledKey])\n\n  // Sync callbacks and options on EVERY render (outside useEffect)\n  for (let i = 0; i < hotkeys.length; i++) {\n    const def = hotkeys[i]!\n    const hotkeyStr = hotkeyStrings[i]!\n    const registrationKey = `${i}:${hotkeyStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeyOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiBA,kDAA0B,CAAC;CAClD,MAAM,mDAA4B;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,mDAA4B;CAExE,MAAM,qDAA2D,IAAI,KAAK,CAAC;CAC3E,MAAM,+BAAoB,QAAQ;CAClC,MAAM,qCAAyC,EAAE,CAAC;CAClD,MAAM,qCAA0B,cAAc;CAC9C,MAAM,sCAA2B,eAAe;CAChD,MAAM,+BAAoB,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,QACjC,OAAO,IAAI,WAAW,WAClB,IAAI,4FACkC,IAAI,QAAQ,SAAS,CAAC,CACjE;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAerB,4BAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiBC,oBAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AACnE,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;AAE3B,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,CA9Fe,cAAc,KAAK,KAAK,EACvB,QAChB,KAAK,QAAQ;AAMZ,SALe;GACb,GAAG;GACH,GAAG;GACH,GAAG,IAAI;GACR,CACa,WAAW;GACzB,CACD,KAAK,KAAK,CAoFa,CAAC;AAG3B,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,MAAM,QAAQ;EACpB,MAAM,YAAY,cAAc;EAChC,MAAM,kBAAkB,GAAG,EAAE,GAAG;EAChC,MAAM,SAAS,iBAAiB,QAAQ,IAAI,gBAAgB,EAAE;AAE9D,MAAI,QAAQ,UAAU;AACpB,UAAO,WAAW,IAAI;GAMtB,MAAM,EAAE,QAAQ,SAAS,GAAG,yBALN;IACpB,GAAG;IACH,GAAG;IACH,GAAG,IAAI;IACR;AAED,UAAO,WAAW,qBAAqB"}
+{"version":3,"file":"useHotkeys.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * React hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).\n *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row\n *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle\n *   via `setOptions` (no unregister/re-register churn).\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    typeof def.hotkey === 'string'\n      ? def.hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n  })\n\n  useEffect(() => {\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [])\n\n  // Sync callbacks and options on EVERY render (outside useEffect)\n  for (let i = 0; i < hotkeys.length; i++) {\n    const def = hotkeys[i]!\n    const hotkeyStr = hotkeyStrings[i]!\n    const registrationKey = `${i}:${hotkeyStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeyOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiBA,kDAA0B,CAAC;CAClD,MAAM,mDAA4B;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,mDAA4B;CAExE,MAAM,qDAA2D,IAAI,KAAK,CAAC;CAC3E,MAAM,+BAAoB,QAAQ;CAClC,MAAM,qCAAyC,EAAE,CAAC;CAClD,MAAM,qCAA0B,cAAc;CAC9C,MAAM,sCAA2B,eAAe;CAChD,MAAM,+BAAoB,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,QACjC,OAAO,IAAI,WAAW,WAClB,IAAI,4FACkC,IAAI,QAAQ,SAAS,CAAC,CACjE;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,4BAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiBC,oBAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AACnE,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;GAC3B;AAEF,4BAAgB;AACd,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,EAAE,CAAC;AAGN,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,MAAM,QAAQ;EACpB,MAAM,YAAY,cAAc;EAChC,MAAM,kBAAkB,GAAG,EAAE,GAAG;EAChC,MAAM,SAAS,iBAAiB,QAAQ,IAAI,gBAAgB,EAAE;AAE9D,MAAI,QAAQ,UAAU;AACpB,UAAO,WAAW,IAAI;GAMtB,MAAM,EAAE,QAAQ,SAAS,GAAG,yBALN;IACpB,GAAG;IACH,GAAG;IACH,GAAG,IAAI;IACR;AAED,UAAO,WAAW,qBAAqB"}

package/dist/useHotkeys.d.cts

@@ -26,7 +26,10 @@ interface UseHotkeyDefinition {
  * Callbacks and options are synced on every render to avoid stale closures.
  *
  * @param hotkeys - Array of hotkey definitions to register
- * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row
+ *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+ *   via `setOptions` (no unregister/re-register churn).
  *
  * @example
  * ```tsx

package/dist/useHotkeys.d.ts

@@ -26,7 +26,10 @@ interface UseHotkeyDefinition {
  * Callbacks and options are synced on every render to avoid stale closures.
  *
  * @param hotkeys - Array of hotkey definitions to register
- * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row
+ *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+ *   via `setOptions` (no unregister/re-register churn).
  *
  * @example
  * ```tsx

package/dist/useHotkeys.js

@@ -17,7 +17,10 @@ import { useEffect, useRef } from "react";
 * Callbacks and options are synced on every render to avoid stale closures.
 *
 * @param hotkeys - Array of hotkey definitions to register
-* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
+*   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row
+*   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+*   via `setOptions` (no unregister/re-register churn).
 *
 * @example
 * ```tsx
@@ -104,17 +107,13 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			});
 		}
 		registrationsRef.current = nextRegistrations;
+	});
+	useEffect(() => {
 		return () => {
 			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
 			registrationsRef.current = /* @__PURE__ */ new Map();
 		};
-	}, [hotkeyStrings.join("\0"), hotkeys.map((def) => {
-		return {
-			...defaultOptions,
-			...commonOptions,
-			...def.options
-		}.enabled ?? true;
-	}).join("\0")]);
+	}, []);
 	for (let i = 0; i < hotkeys.length; i++) {
 		const def = hotkeys[i];
 		const hotkeyStr = hotkeyStrings[i];

package/dist/useHotkeys.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeys.js","names":[],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * React hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    typeof def.hotkey === 'string'\n      ? def.hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  // Stable serialized keys for effect dependencies\n  const hotkeyKey = hotkeyStrings.join('\\0')\n  const enabledKey = hotkeys\n    .map((def) => {\n      const merged = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      }\n      return merged.enabled ?? true\n    })\n    .join('\\0')\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [hotkeyKey, enabledKey])\n\n  // Sync callbacks and options on EVERY render (outside useEffect)\n  for (let i = 0; i < hotkeys.length; i++) {\n    const def = hotkeys[i]!\n    const hotkeyStr = hotkeyStrings[i]!\n    const registrationKey = `${i}:${hotkeyStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeyOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"useHotkeys.js","names":[],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * React hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).\n *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row\n *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle\n *   via `setOptions` (no unregister/re-register churn).\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    typeof def.hotkey === 'string'\n      ? def.hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n  })\n\n  useEffect(() => {\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [])\n\n  // Sync callbacks and options on EVERY render (outside useEffect)\n  for (let i = 0; i < hotkeys.length; i++) {\n    const def = hotkeys[i]!\n    const hotkeyStr = hotkeyStrings[i]!\n    const registrationKey = `${i}:${hotkeyStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeyOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiB,0BAA0B,CAAC;CAClD,MAAM,UAAU,kBAAkB;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,YAAY,gBAAgB;CAExE,MAAM,mBAAmB,uBAAwC,IAAI,KAAK,CAAC;CAC3E,MAAM,aAAa,OAAO,QAAQ;CAClC,MAAM,mBAAmB,OAAsB,EAAE,CAAC;CAClD,MAAM,mBAAmB,OAAO,cAAc;CAC9C,MAAM,oBAAoB,OAAO,eAAe;CAChD,MAAM,aAAa,OAAO,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,QACjC,OAAO,IAAI,WAAW,WAClB,IAAI,SACH,aAAa,wBAAwB,IAAI,QAAQ,SAAS,CAAC,CACjE;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,iBAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiB,MAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AACnE,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;GAC3B;AAEF,iBAAgB;AACd,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,EAAE,CAAC;AAGN,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,MAAM,QAAQ;EACpB,MAAM,YAAY,cAAc;EAChC,MAAM,kBAAkB,GAAG,EAAE,GAAG;EAChC,MAAM,SAAS,iBAAiB,QAAQ,IAAI,gBAAgB,EAAE;AAE9D,MAAI,QAAQ,UAAU;AACpB,UAAO,WAAW,IAAI;GAMtB,MAAM,EAAE,QAAQ,SAAS,GAAG,yBALN;IACpB,GAAG;IACH,GAAG;IACH,GAAG,IAAI;IACR;AAED,UAAO,WAAW,qBAAqB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/index.ts

@@ -11,5 +11,6 @@ export * from './useHeldKeys'
 export * from './useHeldKeyCodes'
 export * from './useKeyHold'
 export * from './useHotkeySequence'
+export * from './useHotkeySequences'
 export * from './useHotkeyRecorder'
 export * from './useHotkeySequenceRecorder'

package/src/useHotkey.ts

@@ -43,7 +43,8 @@ export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
  *
  * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
  * @param callback - The function to call when the hotkey is pressed
- * @param options - Options for the hotkey behavior
+ * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)
+ *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
  *
  * @example
  * ```tsx
@@ -135,6 +136,12 @@ export function useHotkey(
 
     // Skip if no valid target (SSR or ref still null)
     if (!resolvedTarget) {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+      prevTargetRef.current = null
+      prevHotkeyRef.current = null
       return
     }
 
@@ -174,7 +181,7 @@ export function useHotkey(
         registrationRef.current = null
       }
     }
-  }, [hotkeyString, options.enabled])
+  }, [hotkeyString])
 
   // Sync callback and options on EVERY render (outside useEffect)
   // This avoids stale closures - the callback always has access to latest state

package/src/useHotkeySequence.ts

@@ -40,7 +40,8 @@ export interface UseHotkeySequenceOptions extends Omit<
  *
  * @param sequence - Array of hotkey strings that form the sequence
  * @param callback - Function to call when the sequence is completed
- * @param options - Options for the sequence behavior
+ * @param options - Options for the sequence behavior. `enabled: false` keeps the registration (visible in devtools)
+ *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
  *
  * @example
  * ```tsx
@@ -108,6 +109,12 @@ export function useHotkeySequence(
 
   useEffect(() => {
     if (sequenceRef.current.length === 0) {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+      prevTargetRef.current = null
+      prevSequenceRef.current = null
       return
     }
 
@@ -119,6 +126,12 @@ export function useHotkeySequence(
 
     // Skip if no valid target (SSR or ref still null)
     if (!resolvedTarget) {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+      prevTargetRef.current = null
+      prevSequenceRef.current = null
       return
     }
 
@@ -161,7 +174,7 @@ export function useHotkeySequence(
         registrationRef.current = null
       }
     }
-  }, [hotkeySequenceString, mergedOptions.enabled])
+  }, [hotkeySequenceString])
 
   // Sync callback and options on EVERY render (outside useEffect)
   if (registrationRef.current?.isActive) {