@tanstack/react-hotkeys 0.5.0 → 0.6.0

package/dist/HotkeysProvider.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"HotkeysProvider.cjs","names":[],"sources":["../src/HotkeysProvider.tsx"],"sourcesContent":["import React, { createContext, useContext, useMemo } from 'react'\nimport type { ReactNode } from 'react'\nimport type { HotkeyRecorderOptions } from '@tanstack/hotkeys'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type { UseHotkeySequenceOptions } from './useHotkeySequence'\n\nexport interface HotkeysProviderOptions {\n  hotkey?: Partial<UseHotkeyOptions>\n  hotkeyRecorder?: Partial<HotkeyRecorderOptions>\n  hotkeySequence?: Partial<UseHotkeySequenceOptions>\n}\n\ninterface HotkeysContextValue {\n  defaultOptions: HotkeysProviderOptions\n}\n\nconst HotkeysContext = createContext<HotkeysContextValue | null>(null)\n\nexport interface HotkeysProviderProps {\n  children: ReactNode\n  defaultOptions?: HotkeysProviderOptions\n}\n\nconst DEFAULT_OPTIONS: HotkeysProviderOptions = {}\n\nexport function HotkeysProvider({\n  children,\n  defaultOptions = DEFAULT_OPTIONS,\n}: HotkeysProviderProps) {\n  const contextValue: HotkeysContextValue = useMemo(\n    () => ({\n      defaultOptions,\n    }),\n    [defaultOptions],\n  )\n\n  return (\n    // eslint-disable-next-line @eslint-react/no-context-provider -- React 19+ only; we support React >=16.8\n    <HotkeysContext.Provider value={contextValue}>\n      {children}\n    </HotkeysContext.Provider>\n  )\n}\n\nexport function useHotkeysContext() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  return useContext(HotkeysContext)\n}\n\nexport function useDefaultHotkeysOptions() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  const context = useContext(HotkeysContext)\n  return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;;;AAgBA,MAAM,0CAA2D,KAAK;AAOtE,MAAM,kBAA0C,EAAE;AAElD,SAAgB,gBAAgB,EAC9B,UACA,iBAAiB,mBACM;CACvB,MAAM,yCACG,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QAEE,4CAAC,eAAe,UAAhB,EAAyB,OAAO,cAEN,EADvB,SACuB;;AAI9B,SAAgB,oBAAoB;AAElC,8BAAkB,eAAe;;AAGnC,SAAgB,2BAA2B;AAGzC,8BAD2B,eAAe,EAC1B,kBAAkB,EAAE"}
+{"version":3,"file":"HotkeysProvider.cjs","names":[],"sources":["../src/HotkeysProvider.tsx"],"sourcesContent":["import React, { createContext, useContext, useMemo } from 'react'\nimport type { ReactNode } from 'react'\nimport type {\n  HotkeyRecorderOptions,\n  HotkeySequenceRecorderOptions,\n} from '@tanstack/hotkeys'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type { UseHotkeySequenceOptions } from './useHotkeySequence'\n\nexport interface HotkeysProviderOptions {\n  hotkey?: Partial<UseHotkeyOptions>\n  hotkeyRecorder?: Partial<HotkeyRecorderOptions>\n  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>\n  hotkeySequence?: Partial<UseHotkeySequenceOptions>\n}\n\ninterface HotkeysContextValue {\n  defaultOptions: HotkeysProviderOptions\n}\n\nconst HotkeysContext = createContext<HotkeysContextValue | null>(null)\n\nexport interface HotkeysProviderProps {\n  children: ReactNode\n  defaultOptions?: HotkeysProviderOptions\n}\n\nconst DEFAULT_OPTIONS: HotkeysProviderOptions = {}\n\nexport function HotkeysProvider({\n  children,\n  defaultOptions = DEFAULT_OPTIONS,\n}: HotkeysProviderProps) {\n  const contextValue: HotkeysContextValue = useMemo(\n    () => ({\n      defaultOptions,\n    }),\n    [defaultOptions],\n  )\n\n  return (\n    // eslint-disable-next-line @eslint-react/no-context-provider -- React 19+ only; we support React >=16.8\n    <HotkeysContext.Provider value={contextValue}>\n      {children}\n    </HotkeysContext.Provider>\n  )\n}\n\nexport function useHotkeysContext() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  return useContext(HotkeysContext)\n}\n\nexport function useDefaultHotkeysOptions() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  const context = useContext(HotkeysContext)\n  return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;;;AAoBA,MAAM,0CAA2D,KAAK;AAOtE,MAAM,kBAA0C,EAAE;AAElD,SAAgB,gBAAgB,EAC9B,UACA,iBAAiB,mBACM;CACvB,MAAM,yCACG,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QAEE,4CAAC,eAAe,UAAhB,EAAyB,OAAO,cAEN,EADvB,SACuB;;AAI9B,SAAgB,oBAAoB;AAElC,8BAAkB,eAAe;;AAGnC,SAAgB,2BAA2B;AAGzC,8BAD2B,eAAe,EAC1B,kBAAkB,EAAE"}

package/dist/HotkeysProvider.d.cts

@@ -1,12 +1,13 @@
 import { UseHotkeyOptions } from "./useHotkey.cjs";
 import { UseHotkeySequenceOptions } from "./useHotkeySequence.cjs";
-import { HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import React, { ReactNode } from "react";
 
 //#region src/HotkeysProvider.d.ts
 interface HotkeysProviderOptions {
   hotkey?: Partial<UseHotkeyOptions>;
   hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
+  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
   hotkeySequence?: Partial<UseHotkeySequenceOptions>;
 }
 interface HotkeysContextValue {

package/dist/HotkeysProvider.d.ts

@@ -1,12 +1,13 @@
 import { UseHotkeyOptions } from "./useHotkey.js";
 import { UseHotkeySequenceOptions } from "./useHotkeySequence.js";
-import { HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import React, { ReactNode } from "react";
 
 //#region src/HotkeysProvider.d.ts
 interface HotkeysProviderOptions {
   hotkey?: Partial<UseHotkeyOptions>;
   hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
+  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
   hotkeySequence?: Partial<UseHotkeySequenceOptions>;
 }
 interface HotkeysContextValue {

package/dist/HotkeysProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"HotkeysProvider.js","names":[],"sources":["../src/HotkeysProvider.tsx"],"sourcesContent":["import React, { createContext, useContext, useMemo } from 'react'\nimport type { ReactNode } from 'react'\nimport type { HotkeyRecorderOptions } from '@tanstack/hotkeys'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type { UseHotkeySequenceOptions } from './useHotkeySequence'\n\nexport interface HotkeysProviderOptions {\n  hotkey?: Partial<UseHotkeyOptions>\n  hotkeyRecorder?: Partial<HotkeyRecorderOptions>\n  hotkeySequence?: Partial<UseHotkeySequenceOptions>\n}\n\ninterface HotkeysContextValue {\n  defaultOptions: HotkeysProviderOptions\n}\n\nconst HotkeysContext = createContext<HotkeysContextValue | null>(null)\n\nexport interface HotkeysProviderProps {\n  children: ReactNode\n  defaultOptions?: HotkeysProviderOptions\n}\n\nconst DEFAULT_OPTIONS: HotkeysProviderOptions = {}\n\nexport function HotkeysProvider({\n  children,\n  defaultOptions = DEFAULT_OPTIONS,\n}: HotkeysProviderProps) {\n  const contextValue: HotkeysContextValue = useMemo(\n    () => ({\n      defaultOptions,\n    }),\n    [defaultOptions],\n  )\n\n  return (\n    // eslint-disable-next-line @eslint-react/no-context-provider -- React 19+ only; we support React >=16.8\n    <HotkeysContext.Provider value={contextValue}>\n      {children}\n    </HotkeysContext.Provider>\n  )\n}\n\nexport function useHotkeysContext() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  return useContext(HotkeysContext)\n}\n\nexport function useDefaultHotkeysOptions() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  const context = useContext(HotkeysContext)\n  return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;AAgBA,MAAM,iBAAiB,cAA0C,KAAK;AAOtE,MAAM,kBAA0C,EAAE;AAElD,SAAgB,gBAAgB,EAC9B,UACA,iBAAiB,mBACM;CACvB,MAAM,eAAoC,eACjC,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QAEE,oCAAC,eAAe,UAAhB,EAAyB,OAAO,cAEN,EADvB,SACuB;;AAI9B,SAAgB,oBAAoB;AAElC,QAAO,WAAW,eAAe;;AAGnC,SAAgB,2BAA2B;AAGzC,QADgB,WAAW,eAAe,EAC1B,kBAAkB,EAAE"}
+{"version":3,"file":"HotkeysProvider.js","names":[],"sources":["../src/HotkeysProvider.tsx"],"sourcesContent":["import React, { createContext, useContext, useMemo } from 'react'\nimport type { ReactNode } from 'react'\nimport type {\n  HotkeyRecorderOptions,\n  HotkeySequenceRecorderOptions,\n} from '@tanstack/hotkeys'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type { UseHotkeySequenceOptions } from './useHotkeySequence'\n\nexport interface HotkeysProviderOptions {\n  hotkey?: Partial<UseHotkeyOptions>\n  hotkeyRecorder?: Partial<HotkeyRecorderOptions>\n  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>\n  hotkeySequence?: Partial<UseHotkeySequenceOptions>\n}\n\ninterface HotkeysContextValue {\n  defaultOptions: HotkeysProviderOptions\n}\n\nconst HotkeysContext = createContext<HotkeysContextValue | null>(null)\n\nexport interface HotkeysProviderProps {\n  children: ReactNode\n  defaultOptions?: HotkeysProviderOptions\n}\n\nconst DEFAULT_OPTIONS: HotkeysProviderOptions = {}\n\nexport function HotkeysProvider({\n  children,\n  defaultOptions = DEFAULT_OPTIONS,\n}: HotkeysProviderProps) {\n  const contextValue: HotkeysContextValue = useMemo(\n    () => ({\n      defaultOptions,\n    }),\n    [defaultOptions],\n  )\n\n  return (\n    // eslint-disable-next-line @eslint-react/no-context-provider -- React 19+ only; we support React >=16.8\n    <HotkeysContext.Provider value={contextValue}>\n      {children}\n    </HotkeysContext.Provider>\n  )\n}\n\nexport function useHotkeysContext() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  return useContext(HotkeysContext)\n}\n\nexport function useDefaultHotkeysOptions() {\n  // eslint-disable-next-line @eslint-react/no-use-context -- React 19+ only; we support React >=16.8\n  const context = useContext(HotkeysContext)\n  return context?.defaultOptions ?? {}\n}\n"],"mappings":";;;AAoBA,MAAM,iBAAiB,cAA0C,KAAK;AAOtE,MAAM,kBAA0C,EAAE;AAElD,SAAgB,gBAAgB,EAC9B,UACA,iBAAiB,mBACM;CACvB,MAAM,eAAoC,eACjC,EACL,gBACD,GACD,CAAC,eAAe,CACjB;AAED,QAEE,oCAAC,eAAe,UAAhB,EAAyB,OAAO,cAEN,EADvB,SACuB;;AAI9B,SAAgB,oBAAoB;AAElC,QAAO,WAAW,eAAe;;AAGnC,SAAgB,2BAA2B;AAGzC,QADgB,WAAW,eAAe,EAC1B,kBAAkB,EAAE"}

package/dist/index.cjs

@@ -7,6 +7,7 @@ const require_useHeldKeyCodes = require('./useHeldKeyCodes.cjs');
 const require_useKeyHold = require('./useKeyHold.cjs');
 const require_useHotkeySequence = require('./useHotkeySequence.cjs');
 const require_useHotkeyRecorder = require('./useHotkeyRecorder.cjs');
+const require_useHotkeySequenceRecorder = require('./useHotkeySequenceRecorder.cjs');
 
 exports.HotkeysProvider = require_HotkeysProvider.HotkeysProvider;
 exports.useDefaultHotkeysOptions = require_HotkeysProvider.useDefaultHotkeysOptions;
@@ -15,6 +16,7 @@ exports.useHeldKeys = require_useHeldKeys.useHeldKeys;
 exports.useHotkey = require_useHotkey.useHotkey;
 exports.useHotkeyRecorder = require_useHotkeyRecorder.useHotkeyRecorder;
 exports.useHotkeySequence = require_useHotkeySequence.useHotkeySequence;
+exports.useHotkeySequenceRecorder = require_useHotkeySequenceRecorder.useHotkeySequenceRecorder;
 exports.useHotkeys = require_useHotkeys.useHotkeys;
 exports.useHotkeysContext = require_HotkeysProvider.useHotkeysContext;
 exports.useKeyHold = require_useKeyHold.useKeyHold;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/useHotkeySequence.cjs

@@ -11,6 +11,11 @@ let react = require("react");
 * This hook allows you to register multi-key sequences like 'g g' or 'd d'
 * that trigger when the full sequence is pressed within a timeout.
 *
+* Each step may include modifiers. You can chain the same modifier across
+* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
+* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
+* advance the sequence or reset progress.
+*
 * @param sequence - Array of hotkey strings that form the sequence
 * @param callback - Function to call when the sequence is completed
 * @param options - Options for the sequence behavior
@@ -33,6 +38,11 @@ let react = require("react");
 *     deleteInnerWord()
 *   }, { timeout: 500 })
 *
+*   // Same modifier on consecutive steps (bare Shift between chords is ignored)
+*   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
+*     nextAction()
+*   })
+*
 *   return <div>...</div>
 * }
 * ```

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 * @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\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 *   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      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      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, mergedOptions.enabled])\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,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,EACjC;EAIF,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;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,sBAAsB,cAAc,QAAQ,CAAC;AAGjD,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\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      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      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, mergedOptions.enabled])\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,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,EACjC;EAIF,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;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,sBAAsB,cAAc,QAAQ,CAAC;AAGjD,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}

package/dist/useHotkeySequence.d.cts

@@ -15,6 +15,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
  * This hook allows you to register multi-key sequences like 'g g' or 'd d'
  * that trigger when the full sequence is pressed within a timeout.
  *
+ * Each step may include modifiers. You can chain the same modifier across
+ * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
+ * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
+ * advance the sequence or reset progress.
+ *
  * @param sequence - Array of hotkey strings that form the sequence
  * @param callback - Function to call when the sequence is completed
  * @param options - Options for the sequence behavior
@@ -37,6 +42,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
  *     deleteInnerWord()
  *   }, { timeout: 500 })
  *
+ *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
+ *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
+ *     nextAction()
+ *   })
+ *
  *   return <div>...</div>
  * }
  * ```

package/dist/useHotkeySequence.d.ts

@@ -15,6 +15,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
  * This hook allows you to register multi-key sequences like 'g g' or 'd d'
  * that trigger when the full sequence is pressed within a timeout.
  *
+ * Each step may include modifiers. You can chain the same modifier across
+ * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
+ * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
+ * advance the sequence or reset progress.
+ *
  * @param sequence - Array of hotkey strings that form the sequence
  * @param callback - Function to call when the sequence is completed
  * @param options - Options for the sequence behavior
@@ -37,6 +42,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
  *     deleteInnerWord()
  *   }, { timeout: 500 })
  *
+ *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
+ *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
+ *     nextAction()
+ *   })
+ *
  *   return <div>...</div>
  * }
  * ```

package/dist/useHotkeySequence.js

@@ -10,6 +10,11 @@ import { useEffect, useRef } from "react";
 * This hook allows you to register multi-key sequences like 'g g' or 'd d'
 * that trigger when the full sequence is pressed within a timeout.
 *
+* Each step may include modifiers. You can chain the same modifier across
+* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
+* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
+* advance the sequence or reset progress.
+*
 * @param sequence - Array of hotkey strings that form the sequence
 * @param callback - Function to call when the sequence is completed
 * @param options - Options for the sequence behavior
@@ -32,6 +37,11 @@ import { useEffect, useRef } from "react";
 *     deleteInnerWord()
 *   }, { timeout: 500 })
 *
+*   // Same modifier on consecutive steps (bare Shift between chords is ignored)
+*   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
+*     nextAction()
+*   })
+*
 *   return <div>...</div>
 * }
 * ```

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 * @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\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 *   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      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      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, mergedOptions.enabled])\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,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,EACjC;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;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,sBAAsB,cAAc,QAAQ,CAAC;AAGjD,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\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      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      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, mergedOptions.enabled])\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,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,EACjC;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;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,sBAAsB,cAAc,QAAQ,CAAC;AAGjD,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}

package/dist/useHotkeySequenceRecorder.cjs

@@ -0,0 +1,42 @@
+const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
+const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let react = require("react");
+let _tanstack_react_store = require("@tanstack/react-store");
+
+//#region src/useHotkeySequenceRecorder.ts
+/**
+* React hook for recording multi-chord sequences (Vim-style shortcuts).
+*
+* @param options - Configuration options for the hotkey sequence recorder
+*/
+function useHotkeySequenceRecorder(options) {
+	const mergedOptions = {
+		...require_HotkeysProvider.useDefaultHotkeysOptions().hotkeySequenceRecorder,
+		...options
+	};
+	const recorderRef = (0, react.useRef)(null);
+	if (!recorderRef.current) recorderRef.current = new _tanstack_hotkeys.HotkeySequenceRecorder(mergedOptions);
+	recorderRef.current.setOptions(mergedOptions);
+	const isRecording = (0, _tanstack_react_store.useStore)(recorderRef.current.store, (state) => state.isRecording);
+	const steps = (0, _tanstack_react_store.useStore)(recorderRef.current.store, (state) => state.steps);
+	const recordedSequence = (0, _tanstack_react_store.useStore)(recorderRef.current.store, (state) => state.recordedSequence);
+	(0, react.useEffect)(() => {
+		return () => {
+			recorderRef.current?.destroy();
+		};
+	}, []);
+	return {
+		isRecording,
+		steps,
+		recordedSequence,
+		startRecording: () => recorderRef.current?.start(),
+		stopRecording: () => recorderRef.current?.stop(),
+		cancelRecording: () => recorderRef.current?.cancel(),
+		commitRecording: () => recorderRef.current?.commit()
+	};
+}
+
+//#endregion
+exports.useHotkeySequenceRecorder = useHotkeySequenceRecorder;
+//# sourceMappingURL=useHotkeySequenceRecorder.cjs.map

package/dist/useHotkeySequenceRecorder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeySequenceRecorder.cjs","names":["useDefaultHotkeysOptions","HotkeySequenceRecorder"],"sources":["../src/useHotkeySequenceRecorder.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { HotkeySequenceRecorder } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type {\n  HotkeySequence,\n  HotkeySequenceRecorderOptions,\n} from '@tanstack/hotkeys'\n\nexport interface ReactHotkeySequenceRecorder {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** Chords captured in the current session */\n  steps: HotkeySequence\n  /** Last committed sequence */\n  recordedSequence: HotkeySequence | null\n  startRecording: () => void\n  stopRecording: () => void\n  cancelRecording: () => void\n  /** Commit current steps (no-op if empty) */\n  commitRecording: () => void\n}\n\n/**\n * React hook for recording multi-chord sequences (Vim-style shortcuts).\n *\n * @param options - Configuration options for the hotkey sequence recorder\n */\nexport function useHotkeySequenceRecorder(\n  options: HotkeySequenceRecorderOptions,\n): ReactHotkeySequenceRecorder {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequenceRecorder,\n    ...options,\n  } as HotkeySequenceRecorderOptions\n\n  const recorderRef = useRef<HotkeySequenceRecorder | null>(null)\n\n  if (!recorderRef.current) {\n    recorderRef.current = new HotkeySequenceRecorder(mergedOptions)\n  }\n\n  recorderRef.current.setOptions(mergedOptions)\n\n  const isRecording = useStore(\n    recorderRef.current.store,\n    (state) => state.isRecording,\n  )\n  const steps = useStore(recorderRef.current.store, (state) => state.steps)\n  const recordedSequence = useStore(\n    recorderRef.current.store,\n    (state) => state.recordedSequence,\n  )\n\n  useEffect(() => {\n    return () => {\n      recorderRef.current?.destroy()\n    }\n  }, [])\n\n  return {\n    isRecording,\n    steps,\n    recordedSequence,\n    startRecording: () => recorderRef.current?.start(),\n    stopRecording: () => recorderRef.current?.stop(),\n    cancelRecording: () => recorderRef.current?.cancel(),\n    commitRecording: () => recorderRef.current?.commit(),\n  }\n}\n"],"mappings":";;;;;;;;;;;;AA4BA,SAAgB,0BACd,SAC6B;CAC7B,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,gCAAoD,KAAK;AAE/D,KAAI,CAAC,YAAY,QACf,aAAY,UAAU,IAAIC,yCAAuB,cAAc;AAGjE,aAAY,QAAQ,WAAW,cAAc;CAE7C,MAAM,kDACJ,YAAY,QAAQ,QACnB,UAAU,MAAM,YAClB;CACD,MAAM,4CAAiB,YAAY,QAAQ,QAAQ,UAAU,MAAM,MAAM;CACzE,MAAM,uDACJ,YAAY,QAAQ,QACnB,UAAU,MAAM,iBAClB;AAED,4BAAgB;AACd,eAAa;AACX,eAAY,SAAS,SAAS;;IAE/B,EAAE,CAAC;AAEN,QAAO;EACL;EACA;EACA;EACA,sBAAsB,YAAY,SAAS,OAAO;EAClD,qBAAqB,YAAY,SAAS,MAAM;EAChD,uBAAuB,YAAY,SAAS,QAAQ;EACpD,uBAAuB,YAAY,SAAS,QAAQ;EACrD"}

package/dist/useHotkeySequenceRecorder.d.cts

@@ -0,0 +1,25 @@
+import { HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+
+//#region src/useHotkeySequenceRecorder.d.ts
+interface ReactHotkeySequenceRecorder {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** Chords captured in the current session */
+  steps: HotkeySequence;
+  /** Last committed sequence */
+  recordedSequence: HotkeySequence | null;
+  startRecording: () => void;
+  stopRecording: () => void;
+  cancelRecording: () => void;
+  /** Commit current steps (no-op if empty) */
+  commitRecording: () => void;
+}
+/**
+ * React hook for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * @param options - Configuration options for the hotkey sequence recorder
+ */
+declare function useHotkeySequenceRecorder(options: HotkeySequenceRecorderOptions): ReactHotkeySequenceRecorder;
+//#endregion
+export { ReactHotkeySequenceRecorder, useHotkeySequenceRecorder };
+//# sourceMappingURL=useHotkeySequenceRecorder.d.cts.map

package/dist/useHotkeySequenceRecorder.d.ts

@@ -0,0 +1,25 @@
+import { HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+
+//#region src/useHotkeySequenceRecorder.d.ts
+interface ReactHotkeySequenceRecorder {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** Chords captured in the current session */
+  steps: HotkeySequence;
+  /** Last committed sequence */
+  recordedSequence: HotkeySequence | null;
+  startRecording: () => void;
+  stopRecording: () => void;
+  cancelRecording: () => void;
+  /** Commit current steps (no-op if empty) */
+  commitRecording: () => void;
+}
+/**
+ * React hook for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * @param options - Configuration options for the hotkey sequence recorder
+ */
+declare function useHotkeySequenceRecorder(options: HotkeySequenceRecorderOptions): ReactHotkeySequenceRecorder;
+//#endregion
+export { ReactHotkeySequenceRecorder, useHotkeySequenceRecorder };
+//# sourceMappingURL=useHotkeySequenceRecorder.d.ts.map

package/dist/useHotkeySequenceRecorder.js

@@ -0,0 +1,41 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { HotkeySequenceRecorder } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "react";
+import { useStore } from "@tanstack/react-store";
+
+//#region src/useHotkeySequenceRecorder.ts
+/**
+* React hook for recording multi-chord sequences (Vim-style shortcuts).
+*
+* @param options - Configuration options for the hotkey sequence recorder
+*/
+function useHotkeySequenceRecorder(options) {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkeySequenceRecorder,
+		...options
+	};
+	const recorderRef = useRef(null);
+	if (!recorderRef.current) recorderRef.current = new HotkeySequenceRecorder(mergedOptions);
+	recorderRef.current.setOptions(mergedOptions);
+	const isRecording = useStore(recorderRef.current.store, (state) => state.isRecording);
+	const steps = useStore(recorderRef.current.store, (state) => state.steps);
+	const recordedSequence = useStore(recorderRef.current.store, (state) => state.recordedSequence);
+	useEffect(() => {
+		return () => {
+			recorderRef.current?.destroy();
+		};
+	}, []);
+	return {
+		isRecording,
+		steps,
+		recordedSequence,
+		startRecording: () => recorderRef.current?.start(),
+		stopRecording: () => recorderRef.current?.stop(),
+		cancelRecording: () => recorderRef.current?.cancel(),
+		commitRecording: () => recorderRef.current?.commit()
+	};
+}
+
+//#endregion
+export { useHotkeySequenceRecorder };
+//# sourceMappingURL=useHotkeySequenceRecorder.js.map

package/dist/useHotkeySequenceRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeySequenceRecorder.js","names":[],"sources":["../src/useHotkeySequenceRecorder.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { HotkeySequenceRecorder } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type {\n  HotkeySequence,\n  HotkeySequenceRecorderOptions,\n} from '@tanstack/hotkeys'\n\nexport interface ReactHotkeySequenceRecorder {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** Chords captured in the current session */\n  steps: HotkeySequence\n  /** Last committed sequence */\n  recordedSequence: HotkeySequence | null\n  startRecording: () => void\n  stopRecording: () => void\n  cancelRecording: () => void\n  /** Commit current steps (no-op if empty) */\n  commitRecording: () => void\n}\n\n/**\n * React hook for recording multi-chord sequences (Vim-style shortcuts).\n *\n * @param options - Configuration options for the hotkey sequence recorder\n */\nexport function useHotkeySequenceRecorder(\n  options: HotkeySequenceRecorderOptions,\n): ReactHotkeySequenceRecorder {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequenceRecorder,\n    ...options,\n  } as HotkeySequenceRecorderOptions\n\n  const recorderRef = useRef<HotkeySequenceRecorder | null>(null)\n\n  if (!recorderRef.current) {\n    recorderRef.current = new HotkeySequenceRecorder(mergedOptions)\n  }\n\n  recorderRef.current.setOptions(mergedOptions)\n\n  const isRecording = useStore(\n    recorderRef.current.store,\n    (state) => state.isRecording,\n  )\n  const steps = useStore(recorderRef.current.store, (state) => state.steps)\n  const recordedSequence = useStore(\n    recorderRef.current.store,\n    (state) => state.recordedSequence,\n  )\n\n  useEffect(() => {\n    return () => {\n      recorderRef.current?.destroy()\n    }\n  }, [])\n\n  return {\n    isRecording,\n    steps,\n    recordedSequence,\n    startRecording: () => recorderRef.current?.start(),\n    stopRecording: () => recorderRef.current?.stop(),\n    cancelRecording: () => recorderRef.current?.cancel(),\n    commitRecording: () => recorderRef.current?.commit(),\n  }\n}\n"],"mappings":";;;;;;;;;;;AA4BA,SAAgB,0BACd,SAC6B;CAC7B,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,cAAc,OAAsC,KAAK;AAE/D,KAAI,CAAC,YAAY,QACf,aAAY,UAAU,IAAI,uBAAuB,cAAc;AAGjE,aAAY,QAAQ,WAAW,cAAc;CAE7C,MAAM,cAAc,SAClB,YAAY,QAAQ,QACnB,UAAU,MAAM,YAClB;CACD,MAAM,QAAQ,SAAS,YAAY,QAAQ,QAAQ,UAAU,MAAM,MAAM;CACzE,MAAM,mBAAmB,SACvB,YAAY,QAAQ,QACnB,UAAU,MAAM,iBAClB;AAED,iBAAgB;AACd,eAAa;AACX,eAAY,SAAS,SAAS;;IAE/B,EAAE,CAAC;AAEN,QAAO;EACL;EACA;EACA;EACA,sBAAsB,YAAY,SAAS,OAAO;EAClD,qBAAqB,YAAY,SAAS,MAAM;EAChD,uBAAuB,YAAY,SAAS,QAAQ;EACpD,uBAAuB,YAAY,SAAS,QAAQ;EACrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@tanstack/react-store": "^0.9.2",
-    "@tanstack/hotkeys": "0.4.2"
+    "@tanstack/hotkeys": "0.5.0"
   },
   "devDependencies": {
     "@eslint-react/eslint-plugin": "^3.0.0",

package/src/HotkeysProvider.tsx

@@ -1,12 +1,16 @@
 import React, { createContext, useContext, useMemo } from 'react'
 import type { ReactNode } from 'react'
-import type { HotkeyRecorderOptions } from '@tanstack/hotkeys'
+import type {
+  HotkeyRecorderOptions,
+  HotkeySequenceRecorderOptions,
+} from '@tanstack/hotkeys'
 import type { UseHotkeyOptions } from './useHotkey'
 import type { UseHotkeySequenceOptions } from './useHotkeySequence'
 
 export interface HotkeysProviderOptions {
   hotkey?: Partial<UseHotkeyOptions>
   hotkeyRecorder?: Partial<HotkeyRecorderOptions>
+  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>
   hotkeySequence?: Partial<UseHotkeySequenceOptions>
 }
 

package/src/index.ts

@@ -12,3 +12,4 @@ export * from './useHeldKeyCodes'
 export * from './useKeyHold'
 export * from './useHotkeySequence'
 export * from './useHotkeyRecorder'
+export * from './useHotkeySequenceRecorder'

package/src/useHotkeySequence.ts

@@ -33,6 +33,11 @@ export interface UseHotkeySequenceOptions extends Omit<
  * This hook allows you to register multi-key sequences like 'g g' or 'd d'
  * that trigger when the full sequence is pressed within a timeout.
  *
+ * Each step may include modifiers. You can chain the same modifier across
+ * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
+ * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
+ * advance the sequence or reset progress.
+ *
  * @param sequence - Array of hotkey strings that form the sequence
  * @param callback - Function to call when the sequence is completed
  * @param options - Options for the sequence behavior
@@ -55,6 +60,11 @@ export interface UseHotkeySequenceOptions extends Omit<
  *     deleteInnerWord()
  *   }, { timeout: 500 })
  *
+ *   // Same modifier on consecutive steps (bare Shift between chords is ignored)
+ *   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
+ *     nextAction()
+ *   })
+ *
  *   return <div>...</div>
  * }
  * ```

package/src/useHotkeySequenceRecorder.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef } from 'react'
+import { useStore } from '@tanstack/react-store'
+import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type {
+  HotkeySequence,
+  HotkeySequenceRecorderOptions,
+} from '@tanstack/hotkeys'
+
+export interface ReactHotkeySequenceRecorder {
+  /** Whether recording is currently active */
+  isRecording: boolean
+  /** Chords captured in the current session */
+  steps: HotkeySequence
+  /** Last committed sequence */
+  recordedSequence: HotkeySequence | null
+  startRecording: () => void
+  stopRecording: () => void
+  cancelRecording: () => void
+  /** Commit current steps (no-op if empty) */
+  commitRecording: () => void
+}
+
+/**
+ * React hook for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * @param options - Configuration options for the hotkey sequence recorder
+ */
+export function useHotkeySequenceRecorder(
+  options: HotkeySequenceRecorderOptions,
+): ReactHotkeySequenceRecorder {
+  const mergedOptions = {
+    ...useDefaultHotkeysOptions().hotkeySequenceRecorder,
+    ...options,
+  } as HotkeySequenceRecorderOptions
+
+  const recorderRef = useRef<HotkeySequenceRecorder | null>(null)
+
+  if (!recorderRef.current) {
+    recorderRef.current = new HotkeySequenceRecorder(mergedOptions)
+  }
+
+  recorderRef.current.setOptions(mergedOptions)
+
+  const isRecording = useStore(
+    recorderRef.current.store,
+    (state) => state.isRecording,
+  )
+  const steps = useStore(recorderRef.current.store, (state) => state.steps)
+  const recordedSequence = useStore(
+    recorderRef.current.store,
+    (state) => state.recordedSequence,
+  )
+
+  useEffect(() => {
+    return () => {
+      recorderRef.current?.destroy()
+    }
+  }, [])
+
+  return {
+    isRecording,
+    steps,
+    recordedSequence,
+    startRecording: () => recorderRef.current?.start(),
+    stopRecording: () => recorderRef.current?.stop(),
+    cancelRecording: () => recorderRef.current?.cancel(),
+    commitRecording: () => recorderRef.current?.commit(),
+  }
+}