@tanstack/react-hotkeys 0.10.0 → 0.11.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="./media/header_hotkeys.png" alt="TanStack Hotkeys" />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/hotkeys.png"
+      alt="TanStack Hotkeys"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />

package/dist/index.cjs

@@ -10,12 +10,14 @@ const require_useHotkeySequences = require('./useHotkeySequences.cjs');
 const require_useHotkeyRecorder = require('./useHotkeyRecorder.cjs');
 const require_useHotkeyRegistrations = require('./useHotkeyRegistrations.cjs');
 const require_useHotkeySequenceRecorder = require('./useHotkeySequenceRecorder.cjs');
+const require_useHotkeyHint = require('./useHotkeyHint.cjs');
 
 exports.HotkeysProvider = require_HotkeysProvider.HotkeysProvider;
 exports.useDefaultHotkeysOptions = require_HotkeysProvider.useDefaultHotkeysOptions;
 exports.useHeldKeyCodes = require_useHeldKeyCodes.useHeldKeyCodes;
 exports.useHeldKeys = require_useHeldKeys.useHeldKeys;
 exports.useHotkey = require_useHotkey.useHotkey;
+exports.useHotkeyHint = require_useHotkeyHint.useHotkeyHint;
 exports.useHotkeyRecorder = require_useHotkeyRecorder.useHotkeyRecorder;
 exports.useHotkeyRegistrations = require_useHotkeyRegistrations.useHotkeyRegistrations;
 exports.useHotkeySequence = require_useHotkeySequence.useHotkeySequence;

package/dist/index.d.cts

@@ -9,5 +9,6 @@ import { UseHotkeySequenceDefinition, useHotkeySequences } from "./useHotkeySequ
 import { ReactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.cjs";
 import { HotkeyRegistrationsResult, useHotkeyRegistrations } from "./useHotkeyRegistrations.cjs";
 import { ReactHotkeySequenceRecorder, useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.cjs";
+import { useHotkeyHint } from "./useHotkeyHint.cjs";
 export * from "@tanstack/hotkeys";
-export { HotkeyRegistrationsResult, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, ReactHotkeyRecorder, ReactHotkeySequenceRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceDefinition, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeyRegistrationsResult, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, ReactHotkeyRecorder, ReactHotkeySequenceRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceDefinition, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.d.ts

@@ -9,5 +9,6 @@ import { UseHotkeySequenceDefinition, useHotkeySequences } from "./useHotkeySequ
 import { ReactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { HotkeyRegistrationsResult, useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { ReactHotkeySequenceRecorder, useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
+import { useHotkeyHint } from "./useHotkeyHint.js";
 export * from "@tanstack/hotkeys";
-export { HotkeyRegistrationsResult, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, ReactHotkeyRecorder, ReactHotkeySequenceRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceDefinition, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeyRegistrationsResult, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, ReactHotkeyRecorder, ReactHotkeySequenceRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceDefinition, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -9,7 +9,8 @@ import { useHotkeySequences } from "./useHotkeySequences.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
+import { useHotkeyHint } from "./useHotkeyHint.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useHotkey.cjs

@@ -104,17 +104,21 @@ function useHotkey(hotkey, callback, options = {}) {
 		});
 		prevTargetRef.current = resolvedTarget;
 		prevHotkeyRef.current = hotkeyString;
+	});
+	(0, react.useEffect)(() => {
 		return () => {
 			if (registrationRef.current?.isActive) {
 				registrationRef.current.unregister();
 				registrationRef.current = null;
 			}
 		};
-	}, [hotkeyString]);
-	if (registrationRef.current?.isActive) {
-		registrationRef.current.callback = callback;
-		registrationRef.current.setOptions(optionsWithoutTarget);
-	}
+	}, []);
+	(0, react.useEffect)(() => {
+		if (registrationRef.current?.isActive) {
+			registrationRef.current.callback = callback;
+			registrationRef.current.setOptions(optionsWithoutTarget);
+		}
+	});
 }
 
 //#endregion

package/dist/useHotkey.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkey.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference React state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevHotkeyRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeyString])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  // This avoids stale closures - the callback always has access to latest state\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = callback\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,mDAA4B;CAGlC,MAAM,oCAA0D,KAAK;CAGrE,MAAM,gCAAqB,SAAS;CACpC,MAAM,+BAAoB,cAAc;CACxC,MAAM,+BAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,kCAA+D,KAAK;CAC1E,MAAM,kCAAsC,KAAK;CAIjD,MAAM,kEAA2C,QADhC,cAAc,mDAA4B,CACO;CAGlE,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,4BAAgB;EAEd,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,iBAAc,UAAU;AACxB;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;AAGxB,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,aAAa,CAAC;AAIlB,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,WAAW;AACnC,kBAAgB,QAAQ,WAAW,qBAAqB"}
+{"version":3,"file":"useHotkey.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference React state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevHotkeyRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n  })\n\n  useEffect(() => {\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [])\n\n  // Publish option changes after commit, never during render.\n  useEffect(() => {\n    if (registrationRef.current?.isActive) {\n      registrationRef.current.callback = callback\n      registrationRef.current.setOptions(optionsWithoutTarget)\n    }\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,mDAA4B;CAGlC,MAAM,oCAA0D,KAAK;CAGrE,MAAM,gCAAqB,SAAS;CACpC,MAAM,+BAAoB,cAAc;CACxC,MAAM,+BAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,kCAA+D,KAAK;CAC1E,MAAM,kCAAsC,KAAK;CAIjD,MAAM,kEAA2C,QADhC,cAAc,mDAA4B,CACO;CAGlE,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,4BAAgB;EAEd,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,iBAAc,UAAU;AACxB;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;GACxB;AAEF,4BAAgB;AAEd,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,EAAE,CAAC;AAGN,4BAAgB;AACd,MAAI,gBAAgB,SAAS,UAAU;AACrC,mBAAgB,QAAQ,WAAW;AACnC,mBAAgB,QAAQ,WAAW,qBAAqB;;GAE1D"}

package/dist/useHotkey.js

@@ -103,17 +103,21 @@ function useHotkey(hotkey, callback, options = {}) {
 		});
 		prevTargetRef.current = resolvedTarget;
 		prevHotkeyRef.current = hotkeyString;
+	});
+	useEffect(() => {
 		return () => {
 			if (registrationRef.current?.isActive) {
 				registrationRef.current.unregister();
 				registrationRef.current = null;
 			}
 		};
-	}, [hotkeyString]);
-	if (registrationRef.current?.isActive) {
-		registrationRef.current.callback = callback;
-		registrationRef.current.setOptions(optionsWithoutTarget);
-	}
+	}, []);
+	useEffect(() => {
+		if (registrationRef.current?.isActive) {
+			registrationRef.current.callback = callback;
+			registrationRef.current.setOptions(optionsWithoutTarget);
+		}
+	});
 }
 
 //#endregion

package/dist/useHotkey.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkey.js","names":[],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference React state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevHotkeyRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeyString])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  // This avoids stale closures - the callback always has access to latest state\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = callback\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,kBAAkB;CAGlC,MAAM,kBAAkB,OAAwC,KAAK;CAGrE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,gBAAgB,OAAsB,KAAK;CAIjD,MAAM,eAAe,4BAA4B,QADhC,cAAc,YAAY,gBAAgB,CACO;CAGlE,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;EAEd,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,iBAAc,UAAU;AACxB;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;AAGxB,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,aAAa,CAAC;AAIlB,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,WAAW;AACnC,kBAAgB,QAAQ,WAAW,qBAAqB"}
+{"version":3,"file":"useHotkey.js","names":[],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference React state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevHotkeyRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n  })\n\n  useEffect(() => {\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [])\n\n  // Publish option changes after commit, never during render.\n  useEffect(() => {\n    if (registrationRef.current?.isActive) {\n      registrationRef.current.callback = callback\n      registrationRef.current.setOptions(optionsWithoutTarget)\n    }\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,kBAAkB;CAGlC,MAAM,kBAAkB,OAAwC,KAAK;CAGrE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,gBAAgB,OAAsB,KAAK;CAIjD,MAAM,eAAe,4BAA4B,QADhC,cAAc,YAAY,gBAAgB,CACO;CAGlE,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;EAEd,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,iBAAc,UAAU;AACxB;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;GACxB;AAEF,iBAAgB;AAEd,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,EAAE,CAAC;AAGN,iBAAgB;AACd,MAAI,gBAAgB,SAAS,UAAU;AACrC,mBAAgB,QAAQ,WAAW;AACnC,mBAAgB,QAAQ,WAAW,qBAAqB;;GAE1D"}

package/dist/useHotkeyHint.cjs

@@ -0,0 +1,19 @@
+const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let _tanstack_react_store = require("@tanstack/react-store");
+
+//#region src/useHotkeyHint.ts
+/**
+* Returns a boolean indicating whether held modifiers reveal this shortcut.
+* Only visibility changes from held-key updates cause a rerender.
+* Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+* every modifier. Combine with the action's enabled state before showing a badge.
+* This helper does not register a shortcut or check whether its target is focused.
+*/
+function useHotkeyHint(hotkey, options = {}) {
+	return (0, _tanstack_react_store.useSelector)((0, _tanstack_hotkeys.getKeyStateTracker)().store, (state) => (0, _tanstack_hotkeys.matchesHeldModifiers)(hotkey, state.heldKeys, options));
+}
+
+//#endregion
+exports.useHotkeyHint = useHotkeyHint;
+//# sourceMappingURL=useHotkeyHint.cjs.map

package/dist/useHotkeyHint.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyHint.cjs","names":[],"sources":["../src/useHotkeyHint.ts"],"sourcesContent":["import { useSelector } from '@tanstack/react-store'\nimport { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'\nimport type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'\n\n/**\n * Returns a boolean indicating whether held modifiers reveal this shortcut.\n * Only visibility changes from held-key updates cause a rerender.\n * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires\n * every modifier. Combine with the action's enabled state before showing a badge.\n * This helper does not register a shortcut or check whether its target is focused.\n */\nexport function useHotkeyHint(\n  hotkey: RegisterableHotkey,\n  options: HeldModifierOptions = {},\n): boolean {\n  return useSelector(getKeyStateTracker().store, (state) =>\n    matchesHeldModifiers(hotkey, state.heldKeys, options),\n  )\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,cACd,QACA,UAA+B,EAAE,EACxB;AACT,0FAAuC,CAAC,QAAQ,sDACzB,QAAQ,MAAM,UAAU,QAAQ,CACtD"}

package/dist/useHotkeyHint.d.cts

@@ -0,0 +1,14 @@
+import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/useHotkeyHint.d.ts
+/**
+ * Returns a boolean indicating whether held modifiers reveal this shortcut.
+ * Only visibility changes from held-key updates cause a rerender.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+declare function useHotkeyHint(hotkey: RegisterableHotkey, options?: HeldModifierOptions): boolean;
+//#endregion
+export { useHotkeyHint };
+//# sourceMappingURL=useHotkeyHint.d.cts.map

package/dist/useHotkeyHint.d.ts

@@ -0,0 +1,14 @@
+import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/useHotkeyHint.d.ts
+/**
+ * Returns a boolean indicating whether held modifiers reveal this shortcut.
+ * Only visibility changes from held-key updates cause a rerender.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+declare function useHotkeyHint(hotkey: RegisterableHotkey, options?: HeldModifierOptions): boolean;
+//#endregion
+export { useHotkeyHint };
+//# sourceMappingURL=useHotkeyHint.d.ts.map

package/dist/useHotkeyHint.js

@@ -0,0 +1,18 @@
+import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { useSelector } from "@tanstack/react-store";
+
+//#region src/useHotkeyHint.ts
+/**
+* Returns a boolean indicating whether held modifiers reveal this shortcut.
+* Only visibility changes from held-key updates cause a rerender.
+* Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+* every modifier. Combine with the action's enabled state before showing a badge.
+* This helper does not register a shortcut or check whether its target is focused.
+*/
+function useHotkeyHint(hotkey, options = {}) {
+	return useSelector(getKeyStateTracker().store, (state) => matchesHeldModifiers(hotkey, state.heldKeys, options));
+}
+
+//#endregion
+export { useHotkeyHint };
+//# sourceMappingURL=useHotkeyHint.js.map

package/dist/useHotkeyHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyHint.js","names":[],"sources":["../src/useHotkeyHint.ts"],"sourcesContent":["import { useSelector } from '@tanstack/react-store'\nimport { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'\nimport type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'\n\n/**\n * Returns a boolean indicating whether held modifiers reveal this shortcut.\n * Only visibility changes from held-key updates cause a rerender.\n * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires\n * every modifier. Combine with the action's enabled state before showing a badge.\n * This helper does not register a shortcut or check whether its target is focused.\n */\nexport function useHotkeyHint(\n  hotkey: RegisterableHotkey,\n  options: HeldModifierOptions = {},\n): boolean {\n  return useSelector(getKeyStateTracker().store, (state) =>\n    matchesHeldModifiers(hotkey, state.heldKeys, options),\n  )\n}\n"],"mappings":";;;;;;;;;;;AAWA,SAAgB,cACd,QACA,UAA+B,EAAE,EACxB;AACT,QAAO,YAAY,oBAAoB,CAAC,QAAQ,UAC9C,qBAAqB,QAAQ,MAAM,UAAU,QAAQ,CACtD"}

package/dist/useHotkeySequence.cjs

@@ -99,17 +99,21 @@ function useHotkeySequence(sequence, callback, options = {}) {
 		});
 		prevTargetRef.current = resolvedTarget;
 		prevSequenceRef.current = hotkeySequenceString;
+	});
+	(0, react.useEffect)(() => {
 		return () => {
 			if (registrationRef.current?.isActive) {
 				registrationRef.current.unregister();
 				registrationRef.current = null;
 			}
 		};
-	}, [hotkeySequenceString]);
-	if (registrationRef.current?.isActive) {
-		registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
-		registrationRef.current.setOptions(optionsWithoutTarget);
-	}
+	}, []);
+	(0, react.useEffect)(() => {
+		if (registrationRef.current?.isActive) {
+			registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
+			registrationRef.current.setOptions(optionsWithoutTarget);
+		}
+	});
 }
 
 //#endregion

package/dist/useHotkeySequence.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * Each step may include modifiers. You can chain the same modifier across\n * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,\n * Control, Alt, or Meta pressed alone) are ignored while matching—they do not\n * advance the sequence or reset progress.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   // Same modifier on consecutive steps (bare Shift between chords is ignored)\n *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {\n *     nextAction()\n *   })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n  const sequenceRef = useRef(sequence)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n  sequenceRef.current = sequence\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequenceRef.current.length === 0) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequenceRef.current,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeySequenceString])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = (\n      event: KeyboardEvent,\n      context: HotkeyCallbackContext,\n    ) => callbackRef.current(event, context)\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,qDAA8B;CAGpC,MAAM,oCAA4D,KAAK;CAGvE,MAAM,gCAAqB,SAAS;CACpC,MAAM,+BAAoB,cAAc;CACxC,MAAM,+BAAoB,QAAQ;CAClC,MAAM,gCAAqB,SAAS;AAGpC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;AACrB,aAAY,UAAU;CAGtB,MAAM,kCAA+D,KAAK;CAC1E,MAAM,oCAAwC,KAAK;CAGnD,MAAM,mEAA4C,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,4BAAgB;AACd,MAAI,YAAY,QAAQ,WAAW,GAAG;AACpC,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,YAAY,UACX,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,qBAAqB,CAAC;AAG1B,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}
+{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * Each step may include modifiers. You can chain the same modifier across\n * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,\n * Control, Alt, or Meta pressed alone) are ignored while matching—they do not\n * advance the sequence or reset progress.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   // Same modifier on consecutive steps (bare Shift between chords is ignored)\n *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {\n *     nextAction()\n *   })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n  const sequenceRef = useRef(sequence)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n  sequenceRef.current = sequence\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequenceRef.current.length === 0) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequenceRef.current,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n  })\n\n  useEffect(() => {\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [])\n\n  // Publish option changes after commit, never during render.\n  useEffect(() => {\n    if (registrationRef.current?.isActive) {\n      registrationRef.current.callback = (\n        event: KeyboardEvent,\n        context: HotkeyCallbackContext,\n      ) => callbackRef.current(event, context)\n      registrationRef.current.setOptions(optionsWithoutTarget)\n    }\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,qDAA8B;CAGpC,MAAM,oCAA4D,KAAK;CAGvE,MAAM,gCAAqB,SAAS;CACpC,MAAM,+BAAoB,cAAc;CACxC,MAAM,+BAAoB,QAAQ;CAClC,MAAM,gCAAqB,SAAS;AAGpC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;AACrB,aAAY,UAAU;CAGtB,MAAM,kCAA+D,KAAK;CAC1E,MAAM,oCAAwC,KAAK;CAGnD,MAAM,mEAA4C,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,4BAAgB;AACd,MAAI,YAAY,QAAQ,WAAW,GAAG;AACpC,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,YAAY,UACX,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;GAC1B;AAEF,4BAAgB;AAEd,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,EAAE,CAAC;AAGN,4BAAgB;AACd,MAAI,gBAAgB,SAAS,UAAU;AACrC,mBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,mBAAgB,QAAQ,WAAW,qBAAqB;;GAE1D"}

package/dist/useHotkeySequence.js

@@ -98,17 +98,21 @@ function useHotkeySequence(sequence, callback, options = {}) {
 		});
 		prevTargetRef.current = resolvedTarget;
 		prevSequenceRef.current = hotkeySequenceString;
+	});
+	useEffect(() => {
 		return () => {
 			if (registrationRef.current?.isActive) {
 				registrationRef.current.unregister();
 				registrationRef.current = null;
 			}
 		};
-	}, [hotkeySequenceString]);
-	if (registrationRef.current?.isActive) {
-		registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
-		registrationRef.current.setOptions(optionsWithoutTarget);
-	}
+	}, []);
+	useEffect(() => {
+		if (registrationRef.current?.isActive) {
+			registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
+			registrationRef.current.setOptions(optionsWithoutTarget);
+		}
+	});
 }
 
 //#endregion

package/dist/useHotkeySequence.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * Each step may include modifiers. You can chain the same modifier across\n * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,\n * Control, Alt, or Meta pressed alone) are ignored while matching—they do not\n * advance the sequence or reset progress.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   // Same modifier on consecutive steps (bare Shift between chords is ignored)\n *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {\n *     nextAction()\n *   })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n  const sequenceRef = useRef(sequence)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n  sequenceRef.current = sequence\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequenceRef.current.length === 0) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequenceRef.current,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeySequenceString])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = (\n      event: KeyboardEvent,\n      context: HotkeyCallbackContext,\n    ) => callbackRef.current(event, context)\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,oBAAoB;CAGpC,MAAM,kBAAkB,OAA0C,KAAK;CAGvE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;CAClC,MAAM,cAAc,OAAO,SAAS;AAGpC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;AACrB,aAAY,UAAU;CAGtB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,kBAAkB,OAAsB,KAAK;CAGnD,MAAM,uBAAuB,qBAAqB,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;AACd,MAAI,YAAY,QAAQ,WAAW,GAAG;AACpC,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,YAAY,UACX,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,qBAAqB,CAAC;AAG1B,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}
+{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * Each step may include modifiers. You can chain the same modifier across\n * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,\n * Control, Alt, or Meta pressed alone) are ignored while matching—they do not\n * advance the sequence or reset progress.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior. `enabled: false` keeps the registration (visible in devtools)\n *   and only suppresses firing; the hook updates the existing handle instead of unregistering.\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   // Same modifier on consecutive steps (bare Shift between chords is ignored)\n *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {\n *     nextAction()\n *   })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n  const sequenceRef = useRef(sequence)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n  sequenceRef.current = sequence\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequenceRef.current.length === 0) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n      prevTargetRef.current = null\n      prevSequenceRef.current = null\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequenceRef.current,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n  })\n\n  useEffect(() => {\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [])\n\n  // Publish option changes after commit, never during render.\n  useEffect(() => {\n    if (registrationRef.current?.isActive) {\n      registrationRef.current.callback = (\n        event: KeyboardEvent,\n        context: HotkeyCallbackContext,\n      ) => callbackRef.current(event, context)\n      registrationRef.current.setOptions(optionsWithoutTarget)\n    }\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,oBAAoB;CAGpC,MAAM,kBAAkB,OAA0C,KAAK;CAGvE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;CAClC,MAAM,cAAc,OAAO,SAAS;AAGpC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;AACrB,aAAY,UAAU;CAGtB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,kBAAkB,OAAsB,KAAK;CAGnD,MAAM,uBAAuB,qBAAqB,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;AACd,MAAI,YAAY,QAAQ,WAAW,GAAG;AACpC,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,gBAAgB;AACnB,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;AAE5B,iBAAc,UAAU;AACxB,mBAAgB,UAAU;AAC1B;;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,YAAY,UACX,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;GAC1B;AAEF,iBAAgB;AAEd,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,EAAE,CAAC;AAGN,iBAAgB;AACd,MAAI,gBAAgB,SAAS,UAAU;AACrC,mBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,mBAAgB,QAAQ,WAAW,qBAAqB;;GAE1D"}

package/dist/useHotkeySequences.cjs

@@ -96,6 +96,9 @@ function useHotkeySequences(definitions, commonOptions = {}) {
 			const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row;
 			const existing = prevRegistrations.get(registrationKey);
 			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				existing.handle.callback = def.callback;
+				const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+				existing.handle.setOptions(optionsWithoutTarget);
 				nextRegistrations.set(registrationKey, existing);
 				continue;
 			}
@@ -117,21 +120,6 @@ function useHotkeySequences(definitions, commonOptions = {}) {
 			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

package/dist/useHotkeySequences.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequences.cjs","names":["useDefaultHotkeysOptions","isRef"],"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,iBAAiBA,kDAA0B,CAAC;CAClD,MAAM,qDAA8B;CAEpC,MAAM,qDAA2D,IAAI,KAAK,CAAC;CAC3E,MAAM,mCAAwB,YAAY;CAC1C,MAAM,uCAA2C,EAAE,CAAC;CACpD,MAAM,qCAA0B,cAAc;CAC9C,MAAM,sCAA2B,eAAe;CAChD,MAAM,+BAAoB,QAAQ;CAElC,MAAM,kBAAkB,YAAY,KAAK,oDAClB,IAAI,SAAS,CACnC;AAED,gBAAe,UAAU;AACzB,oBAAmB,UAAU;AAC7B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,4BAAgB;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,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;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,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;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"}
+{"version":3,"file":"useHotkeySequences.cjs","names":["useDefaultHotkeysOptions","isRef"],"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        // Publish callback/options only after commit, never during render.\n        existing.handle.callback = def.callback\n        const { target: _target, ...optionsWithoutTarget } = mergedOptions\n        existing.handle.setOptions(optionsWithoutTarget)\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,SAAgB,mBACd,aACA,gBAA0C,EAAE,EACtC;CAMN,MAAM,iBAAiBA,kDAA0B,CAAC;CAClD,MAAM,qDAA8B;CAEpC,MAAM,qDAA2D,IAAI,KAAK,CAAC;CAC3E,MAAM,mCAAwB,YAAY;CAC1C,MAAM,uCAA2C,EAAE,CAAC;CACpD,MAAM,qCAA0B,cAAc;CAC9C,MAAM,sCAA2B,eAAe;CAChD,MAAM,+BAAoB,QAAQ;CAElC,MAAM,kBAAkB,YAAY,KAAK,oDAClB,IAAI,SAAS,CACnC;AAED,gBAAe,UAAU;AACzB,oBAAmB,UAAU;AAC7B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,4BAAgB;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,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;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;AAEnE,aAAS,OAAO,WAAW,IAAI;IAC/B,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AACrD,aAAS,OAAO,WAAW,qBAAqB;AAChD,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,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"}

package/dist/useHotkeySequences.js

@@ -95,6 +95,9 @@ function useHotkeySequences(definitions, commonOptions = {}) {
 			const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row;
 			const existing = prevRegistrations.get(registrationKey);
 			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				existing.handle.callback = def.callback;
+				const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+				existing.handle.setOptions(optionsWithoutTarget);
 				nextRegistrations.set(registrationKey, existing);
 				continue;
 			}
@@ -116,21 +119,6 @@ function useHotkeySequences(definitions, commonOptions = {}) {
 			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

package/dist/useHotkeySequences.js.map

@@ -1 +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"}
+{"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        // Publish callback/options only after commit, never during render.\n        existing.handle.callback = def.callback\n        const { target: _target, ...optionsWithoutTarget } = mergedOptions\n        existing.handle.setOptions(optionsWithoutTarget)\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"],"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;AAEnE,aAAS,OAAO,WAAW,IAAI;IAC/B,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AACrD,aAAS,OAAO,WAAW,qBAAqB;AAChD,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"}

package/dist/useHotkeys.cjs

@@ -94,6 +94,9 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } = row;
 			const existing = prevRegistrations.get(registrationKey);
 			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				existing.handle.callback = def.callback;
+				const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+				existing.handle.setOptions(optionsWithoutTarget);
 				nextRegistrations.set(registrationKey, existing);
 				continue;
 			}
@@ -115,21 +118,6 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			registrationsRef.current = /* @__PURE__ */ new Map();
 		};
 	}, []);
-	for (let i = 0; i < hotkeys.length; i++) {
-		const def = hotkeys[i];
-		const hotkeyStr = hotkeyStrings[i];
-		const registrationKey = `${i}:${hotkeyStr}`;
-		const handle = registrationsRef.current.get(registrationKey)?.handle;
-		if (handle?.isActive) {
-			handle.callback = def.callback;
-			const { target: _target, ...optionsWithoutTarget } = {
-				...defaultOptions,
-				...commonOptions,
-				...def.options
-			};
-			handle.setOptions(optionsWithoutTarget);
-		}
-	}
 }
 
 //#endregion

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  getHotkeyManager,\n  normalizeRegisterableHotkey,\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    normalizeRegisterableHotkey(def.hotkey, platform),\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,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,2DACL,IAAI,QAAQ,SAAS,CAClD;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"}
+{"version":3,"file":"useHotkeys.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\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    normalizeRegisterableHotkey(def.hotkey, platform),\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        // Publish callback/options only after commit, never during render.\n        existing.handle.callback = def.callback\n        const { target: _target, ...optionsWithoutTarget } = mergedOptions\n        existing.handle.setOptions(optionsWithoutTarget)\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,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,2DACL,IAAI,QAAQ,SAAS,CAClD;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;AAEnE,aAAS,OAAO,WAAW,IAAI;IAC/B,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AACrD,aAAS,OAAO,WAAW,qBAAqB;AAChD,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"}

package/dist/useHotkeys.js

@@ -93,6 +93,9 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } = row;
 			const existing = prevRegistrations.get(registrationKey);
 			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				existing.handle.callback = def.callback;
+				const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+				existing.handle.setOptions(optionsWithoutTarget);
 				nextRegistrations.set(registrationKey, existing);
 				continue;
 			}
@@ -114,21 +117,6 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			registrationsRef.current = /* @__PURE__ */ new Map();
 		};
 	}, []);
-	for (let i = 0; i < hotkeys.length; i++) {
-		const def = hotkeys[i];
-		const hotkeyStr = hotkeyStrings[i];
-		const registrationKey = `${i}:${hotkeyStr}`;
-		const handle = registrationsRef.current.get(registrationKey)?.handle;
-		if (handle?.isActive) {
-			handle.callback = def.callback;
-			const { target: _target, ...optionsWithoutTarget } = {
-				...defaultOptions,
-				...commonOptions,
-				...def.options
-			};
-			handle.setOptions(optionsWithoutTarget);
-		}
-	}
 }
 
 //#endregion

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  getHotkeyManager,\n  normalizeRegisterableHotkey,\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    normalizeRegisterableHotkey(def.hotkey, platform),\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,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,4BAA4B,IAAI,QAAQ,SAAS,CAClD;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"}
+{"version":3,"file":"useHotkeys.js","names":[],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\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    normalizeRegisterableHotkey(def.hotkey, platform),\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        // Publish callback/options only after commit, never during render.\n        existing.handle.callback = def.callback\n        const { target: _target, ...optionsWithoutTarget } = mergedOptions\n        existing.handle.setOptions(optionsWithoutTarget)\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,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,4BAA4B,IAAI,QAAQ,SAAS,CAClD;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;AAEnE,aAAS,OAAO,WAAW,IAAI;IAC/B,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AACrD,aAAS,OAAO,WAAW,qBAAqB;AAChD,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@tanstack/react-store": "^0.11.0",
-    "@tanstack/hotkeys": "0.8.0"
+    "@tanstack/hotkeys": "0.9.0"
   },
   "devDependencies": {
     "@eslint-react/eslint-plugin": "^4.2.3",

package/src/index.ts

@@ -15,3 +15,4 @@ export * from './useHotkeySequences'
 export * from './useHotkeyRecorder'
 export * from './useHotkeyRegistrations'
 export * from './useHotkeySequenceRecorder'
+export * from './useHotkeyHint'

package/src/useHotkey.ts

@@ -168,7 +168,9 @@ export function useHotkey(
     // Update tracking refs
     prevTargetRef.current = resolvedTarget
     prevHotkeyRef.current = hotkeyString
+  })
 
+  useEffect(() => {
     // Cleanup on unmount
     return () => {
       if (registrationRef.current?.isActive) {
@@ -176,12 +178,13 @@ export function useHotkey(
         registrationRef.current = null
       }
     }
-  }, [hotkeyString])
-
-  // Sync callback and options on EVERY render (outside useEffect)
-  // This avoids stale closures - the callback always has access to latest state
-  if (registrationRef.current?.isActive) {
-    registrationRef.current.callback = callback
-    registrationRef.current.setOptions(optionsWithoutTarget)
-  }
+  }, [])
+
+  // Publish option changes after commit, never during render.
+  useEffect(() => {
+    if (registrationRef.current?.isActive) {
+      registrationRef.current.callback = callback
+      registrationRef.current.setOptions(optionsWithoutTarget)
+    }
+  })
 }

package/src/useHotkeyHint.ts

@@ -0,0 +1,19 @@
+import { useSelector } from '@tanstack/react-store'
+import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'
+import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'
+
+/**
+ * Returns a boolean indicating whether held modifiers reveal this shortcut.
+ * Only visibility changes from held-key updates cause a rerender.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+export function useHotkeyHint(
+  hotkey: RegisterableHotkey,
+  options: HeldModifierOptions = {},
+): boolean {
+  return useSelector(getKeyStateTracker().store, (state) =>
+    matchesHeldModifiers(hotkey, state.heldKeys, options),
+  )
+}

package/src/useHotkeySequence.ts

@@ -166,7 +166,9 @@ export function useHotkeySequence(
     // Update tracking refs
     prevTargetRef.current = resolvedTarget
     prevSequenceRef.current = hotkeySequenceString
+  })
 
+  useEffect(() => {
     // Cleanup on unmount
     return () => {
       if (registrationRef.current?.isActive) {
@@ -174,14 +176,16 @@ export function useHotkeySequence(
         registrationRef.current = null
       }
     }
-  }, [hotkeySequenceString])
-
-  // Sync callback and options on EVERY render (outside useEffect)
-  if (registrationRef.current?.isActive) {
-    registrationRef.current.callback = (
-      event: KeyboardEvent,
-      context: HotkeyCallbackContext,
-    ) => callbackRef.current(event, context)
-    registrationRef.current.setOptions(optionsWithoutTarget)
-  }
+  }, [])
+
+  // Publish option changes after commit, never during render.
+  useEffect(() => {
+    if (registrationRef.current?.isActive) {
+      registrationRef.current.callback = (
+        event: KeyboardEvent,
+        context: HotkeyCallbackContext,
+      ) => callbackRef.current(event, context)
+      registrationRef.current.setOptions(optionsWithoutTarget)
+    }
+  })
 }

package/src/useHotkeySequences.ts

@@ -154,6 +154,10 @@ export function useHotkeySequences(
 
       const existing = prevRegistrations.get(registrationKey)
       if (existing?.handle.isActive && existing.target === resolvedTarget) {
+        // Publish callback/options only after commit, never during render.
+        existing.handle.callback = def.callback
+        const { target: _target, ...optionsWithoutTarget } = mergedOptions
+        existing.handle.setOptions(optionsWithoutTarget)
         nextRegistrations.set(registrationKey, existing)
         continue
       }
@@ -185,22 +189,4 @@ export function useHotkeySequences(
       registrationsRef.current = 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 mergedOptions = {
-        ...defaultOptions,
-        ...commonOptions,
-        ...def.options,
-      } as UseHotkeySequenceOptions
-      const { target: _target, ...optionsWithoutTarget } = mergedOptions
-      handle.setOptions(optionsWithoutTarget)
-    }
-  }
 }

package/src/useHotkeys.ts

@@ -155,6 +155,10 @@ export function useHotkeys(
 
       const existing = prevRegistrations.get(registrationKey)
       if (existing?.handle.isActive && existing.target === resolvedTarget) {
+        // Publish callback/options only after commit, never during render.
+        existing.handle.callback = def.callback
+        const { target: _target, ...optionsWithoutTarget } = mergedOptions
+        existing.handle.setOptions(optionsWithoutTarget)
         nextRegistrations.set(registrationKey, existing)
         continue
       }
@@ -186,23 +190,4 @@ export function useHotkeys(
       registrationsRef.current = new Map()
     }
   }, [])
-
-  // Sync callbacks and options on EVERY render (outside useEffect)
-  for (let i = 0; i < hotkeys.length; i++) {
-    const def = hotkeys[i]!
-    const hotkeyStr = hotkeyStrings[i]!
-    const registrationKey = `${i}:${hotkeyStr}`
-    const handle = registrationsRef.current.get(registrationKey)?.handle
-
-    if (handle?.isActive) {
-      handle.callback = def.callback
-      const mergedOptions = {
-        ...defaultOptions,
-        ...commonOptions,
-        ...def.options,
-      } as UseHotkeyOptions
-      const { target: _target, ...optionsWithoutTarget } = mergedOptions
-      handle.setOptions(optionsWithoutTarget)
-    }
-  }
 }