@tanstack/vue-hotkeys 0.4.2 → 0.5.0

package/dist/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_HotkeysProviderContext = require('./HotkeysProviderContext.cjs');
 const require_HotkeysProvider = require('./HotkeysProvider.cjs');
 const require_useHotkey = require('./useHotkey.cjs');
+const require_useHotkeys = require('./useHotkeys.cjs');
 const require_useHeldKeys = require('./useHeldKeys.cjs');
 const require_useHeldKeyCodes = require('./useHeldKeyCodes.cjs');
 const require_useKeyHold = require('./useKeyHold.cjs');
@@ -16,6 +17,7 @@ exports.useHeldKeys = require_useHeldKeys.useHeldKeys;
 exports.useHotkey = require_useHotkey.useHotkey;
 exports.useHotkeyRecorder = require_useHotkeyRecorder.useHotkeyRecorder;
 exports.useHotkeySequence = require_useHotkeySequence.useHotkeySequence;
+exports.useHotkeys = require_useHotkeys.useHotkeys;
 exports.useHotkeysContext = require_HotkeysProviderContext.useHotkeysContext;
 exports.useKeyHold = require_useKeyHold.useKeyHold;
 var _tanstack_hotkeys = require("@tanstack/hotkeys");

package/dist/index.d.cts

@@ -2,9 +2,10 @@ import { UseHotkeyOptions, useHotkey } from "./useHotkey.cjs";
 import { UseHotkeySequenceOptions, useHotkeySequence } from "./useHotkeySequence.cjs";
 import { HotkeysProviderOptions, provideHotkeysContext, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProviderContext.cjs";
 import { HotkeysProvider } from "./HotkeysProvider.cjs";
+import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.cjs";
 import { useHeldKeys } from "./useHeldKeys.cjs";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.cjs";
 import { useKeyHold } from "./useKeyHold.cjs";
 import { VueHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.cjs";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, UseHotkeyOptions, UseHotkeySequenceOptions, VueHotkeyRecorder, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceOptions, VueHotkeyRecorder, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.d.ts

@@ -2,9 +2,10 @@ import { UseHotkeyOptions, useHotkey } from "./useHotkey.js";
 import { UseHotkeySequenceOptions, useHotkeySequence } from "./useHotkeySequence.js";
 import { HotkeysProviderOptions, provideHotkeysContext, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProviderContext.js";
 import { HotkeysProvider } from "./HotkeysProvider.js";
+import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { VueHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, UseHotkeyOptions, UseHotkeySequenceOptions, VueHotkeyRecorder, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceOptions, VueHotkeyRecorder, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { provideHotkeysContext, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProviderContext.js";
 import { HotkeysProvider } from "./HotkeysProvider.js";
 import { useHotkey } from "./useHotkey.js";
+import { useHotkeys } from "./useHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
@@ -9,4 +10,4 @@ import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useHotkeys.cjs

@@ -0,0 +1,140 @@
+const require_HotkeysProviderContext = require('./HotkeysProviderContext.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let vue = require("vue");
+
+//#region src/useHotkeys.ts
+/**
+* Vue composable for registering multiple keyboard hotkeys at once.
+*
+* Uses the singleton HotkeyManager for efficient event handling.
+* Accepts a dynamic array of hotkey definitions, making it safe to use
+* with variable-length lists.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* @param hotkeys - Array of hotkey definitions to register, or a getter/ref
+* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+*
+* @example
+* ```vue
+* <script setup>
+* import { useHotkeys } from '@tanstack/vue-hotkeys'
+*
+* useHotkeys([
+*   { hotkey: 'Mod+S', callback: () => save() },
+*   { hotkey: 'Mod+Z', callback: () => undo() },
+*   { hotkey: 'Escape', callback: () => close() },
+* ])
+* <\/script>
+* ```
+*
+* @example
+* ```vue
+* <script setup>
+* import { computed } from 'vue'
+* import { useHotkeys } from '@tanstack/vue-hotkeys'
+*
+* const items = computed(() => [...])
+* // Dynamic hotkeys from reactive data
+* useHotkeys(
+*   () => items.value.map((item) => ({
+*     hotkey: item.shortcut,
+*     callback: item.action,
+*     options: { enabled: item.enabled },
+*   })),
+*   { preventDefault: true },
+* )
+* <\/script>
+* ```
+*/
+function useHotkeys(hotkeys, commonOptions = {}) {
+	const defaultOptions = require_HotkeysProviderContext.useDefaultHotkeysOptions();
+	const manager = (0, _tanstack_hotkeys.getHotkeyManager)();
+	const registrations = /* @__PURE__ */ new Map();
+	const stopWatcher = (0, vue.watch)(() => {
+		const resolvedHotkeys = resolveMaybeRefOrGetter(hotkeys);
+		const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions);
+		return resolvedHotkeys.map((def, i) => {
+			const resolvedHotkey = resolveMaybeRefOrGetter(def.hotkey);
+			const resolvedDefOptions = def.options ? resolveMaybeRefOrGetter(def.options) : {};
+			const mergedOptions = {
+				...defaultOptions.hotkey,
+				...resolvedCommonOptions,
+				...resolvedDefOptions
+			};
+			const platform = mergedOptions.platform ?? (0, _tanstack_hotkeys.detectPlatform)();
+			const hotkeyString = typeof resolvedHotkey === "string" ? resolvedHotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(resolvedHotkey, platform));
+			const resolvedEnabled = mergedOptions.enabled === void 0 ? void 0 : resolveMaybeRefOrGetter(mergedOptions.enabled);
+			const resolvedTarget = mergedOptions.target === void 0 ? void 0 : resolveMaybeRefOrGetter(mergedOptions.target);
+			return {
+				index: i,
+				hotkeyString,
+				callback: def.callback,
+				mergedOptions,
+				resolvedEnabled,
+				resolvedTarget
+			};
+		});
+	}, (resolved) => {
+		const nextKeys = /* @__PURE__ */ new Set();
+		const prepared = [];
+		for (const entry of resolved) {
+			const finalTarget = entry.resolvedTarget ?? (typeof document !== "undefined" ? document : null);
+			if (!finalTarget) continue;
+			const registrationKey = `${entry.index}:${entry.hotkeyString}`;
+			nextKeys.add(registrationKey);
+			prepared.push({
+				registrationKey,
+				entry,
+				finalTarget
+			});
+		}
+		for (const [key, record] of [...registrations.entries()]) if (!nextKeys.has(key)) {
+			if (record.handle.isActive) record.handle.unregister();
+			registrations.delete(key);
+		}
+		for (const { registrationKey, entry, finalTarget } of prepared) {
+			const existing = registrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === finalTarget) {
+				existing.handle.callback = entry.callback;
+				const { target: _target, enabled: _enabled, ...restOptions } = entry.mergedOptions;
+				const optionsWithoutTarget = {
+					...restOptions,
+					...entry.resolvedEnabled === void 0 ? {} : { enabled: entry.resolvedEnabled }
+				};
+				existing.handle.setOptions(optionsWithoutTarget);
+				continue;
+			}
+			if (existing) {
+				if (existing.handle.isActive) existing.handle.unregister();
+				registrations.delete(registrationKey);
+			}
+			const { target: _target, enabled: _enabled, ...restOptions } = entry.mergedOptions;
+			const optionsWithoutTarget = {
+				...restOptions,
+				...entry.resolvedEnabled === void 0 ? {} : { enabled: entry.resolvedEnabled }
+			};
+			const handle = manager.register(entry.hotkeyString, entry.callback, {
+				...optionsWithoutTarget,
+				target: finalTarget
+			});
+			registrations.set(registrationKey, {
+				handle,
+				target: finalTarget
+			});
+		}
+	}, { immediate: true });
+	(0, vue.onUnmounted)(() => {
+		stopWatcher();
+		for (const { handle } of registrations.values()) if (handle.isActive) handle.unregister();
+		registrations.clear();
+	});
+}
+function resolveMaybeRefOrGetter(value) {
+	return typeof value === "function" ? value() : (0, vue.unref)(value);
+}
+
+//#endregion
+exports.useHotkeys = useHotkeys;
+//# sourceMappingURL=useHotkeys.cjs.map

package/dist/useHotkeys.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeys.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { onUnmounted, unref, watch } from 'vue'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProviderContext'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport type { MaybeRefOrGetter } from 'vue'\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: MaybeRefOrGetter<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?: MaybeRefOrGetter<UseHotkeyOptions>\n}\n\n/**\n * Vue composable 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.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * @param hotkeys - Array of hotkey definitions to register, or a getter/ref\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)\n *\n * @example\n * ```vue\n * <script setup>\n * import { useHotkeys } from '@tanstack/vue-hotkeys'\n *\n * useHotkeys([\n *   { hotkey: 'Mod+S', callback: () => save() },\n *   { hotkey: 'Mod+Z', callback: () => undo() },\n *   { hotkey: 'Escape', callback: () => close() },\n * ])\n * </script>\n * ```\n *\n * @example\n * ```vue\n * <script setup>\n * import { computed } from 'vue'\n * import { useHotkeys } from '@tanstack/vue-hotkeys'\n *\n * const items = computed(() => [...])\n * // Dynamic hotkeys from reactive data\n * useHotkeys(\n *   () => items.value.map((item) => ({\n *     hotkey: item.shortcut,\n *     callback: item.action,\n *     options: { enabled: item.enabled },\n *   })),\n *   { preventDefault: true },\n * )\n * </script>\n * ```\n */\nexport function useHotkeys(\n  hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>,\n  commonOptions: MaybeRefOrGetter<UseHotkeyOptions> = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions()\n  const manager = getHotkeyManager()\n\n  const registrations = new Map<string, RegistrationRecord>()\n\n  const stopWatcher = watch(\n    () => {\n      const resolvedHotkeys = resolveMaybeRefOrGetter(hotkeys)\n      const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions)\n\n      return resolvedHotkeys.map((def, i) => {\n        const resolvedHotkey = resolveMaybeRefOrGetter(def.hotkey)\n        const resolvedDefOptions = def.options\n          ? resolveMaybeRefOrGetter(def.options)\n          : {}\n\n        const mergedOptions = {\n          ...defaultOptions.hotkey,\n          ...resolvedCommonOptions,\n          ...resolvedDefOptions,\n        } as UseHotkeyOptions\n\n        const platform = mergedOptions.platform ?? detectPlatform()\n        const hotkeyString: Hotkey =\n          typeof resolvedHotkey === 'string'\n            ? resolvedHotkey\n            : (formatHotkey(\n                rawHotkeyToParsedHotkey(resolvedHotkey as any, platform),\n              ) as Hotkey)\n\n        const resolvedEnabled =\n          mergedOptions.enabled === undefined\n            ? undefined\n            : resolveMaybeRefOrGetter(mergedOptions.enabled)\n        const resolvedTarget =\n          mergedOptions.target === undefined\n            ? undefined\n            : resolveMaybeRefOrGetter(mergedOptions.target as any)\n\n        return {\n          index: i,\n          hotkeyString,\n          callback: def.callback,\n          mergedOptions,\n          resolvedEnabled,\n          resolvedTarget,\n        }\n      })\n    },\n    (resolved) => {\n      const nextKeys = new Set<string>()\n      const prepared: Array<{\n        registrationKey: string\n        entry: (typeof resolved)[number]\n        finalTarget: Document | HTMLElement | Window\n      }> = []\n\n      for (const entry of resolved) {\n        const finalTarget =\n          entry.resolvedTarget ??\n          (typeof document !== 'undefined' ? document : null)\n\n        if (!finalTarget) {\n          continue\n        }\n\n        const registrationKey = `${entry.index}:${entry.hotkeyString}`\n        nextKeys.add(registrationKey)\n        prepared.push({ registrationKey, entry, finalTarget })\n      }\n\n      for (const [key, record] of [...registrations.entries()]) {\n        if (!nextKeys.has(key)) {\n          if (record.handle.isActive) {\n            record.handle.unregister()\n          }\n          registrations.delete(key)\n        }\n      }\n\n      for (const { registrationKey, entry, finalTarget } of prepared) {\n        const existing = registrations.get(registrationKey)\n        if (existing?.handle.isActive && existing.target === finalTarget) {\n          existing.handle.callback = entry.callback\n          const {\n            target: _target,\n            enabled: _enabled,\n            ...restOptions\n          } = entry.mergedOptions\n          const optionsWithoutTarget = {\n            ...restOptions,\n            ...(entry.resolvedEnabled === undefined\n              ? {}\n              : { enabled: entry.resolvedEnabled }),\n          }\n          existing.handle.setOptions(optionsWithoutTarget)\n          continue\n        }\n\n        if (existing) {\n          if (existing.handle.isActive) {\n            existing.handle.unregister()\n          }\n          registrations.delete(registrationKey)\n        }\n\n        const {\n          target: _target,\n          enabled: _enabled,\n          ...restOptions\n        } = entry.mergedOptions\n        const optionsWithoutTarget = {\n          ...restOptions,\n          ...(entry.resolvedEnabled === undefined\n            ? {}\n            : { enabled: entry.resolvedEnabled }),\n        }\n\n        const handle = manager.register(entry.hotkeyString, entry.callback, {\n          ...optionsWithoutTarget,\n          target: finalTarget,\n        })\n        registrations.set(registrationKey, { handle, target: finalTarget })\n      }\n    },\n    { immediate: true },\n  )\n\n  onUnmounted(() => {\n    stopWatcher()\n    for (const { handle } of registrations.values()) {\n      if (handle.isActive) {\n        handle.unregister()\n      }\n    }\n    registrations.clear()\n  })\n}\n\nfunction resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {\n  return typeof value === 'function' ? (value as () => T)() : unref(value)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,WACd,SACA,gBAAoD,EAAE,EAChD;CAMN,MAAM,iBAAiBA,yDAA0B;CACjD,MAAM,mDAA4B;CAElC,MAAM,gCAAgB,IAAI,KAAiC;CAE3D,MAAM,mCACE;EACJ,MAAM,kBAAkB,wBAAwB,QAAQ;EACxD,MAAM,wBAAwB,wBAAwB,cAAc;AAEpE,SAAO,gBAAgB,KAAK,KAAK,MAAM;GACrC,MAAM,iBAAiB,wBAAwB,IAAI,OAAO;GAC1D,MAAM,qBAAqB,IAAI,UAC3B,wBAAwB,IAAI,QAAQ,GACpC,EAAE;GAEN,MAAM,gBAAgB;IACpB,GAAG,eAAe;IAClB,GAAG;IACH,GAAG;IACJ;GAED,MAAM,WAAW,cAAc,mDAA4B;GAC3D,MAAM,eACJ,OAAO,mBAAmB,WACtB,oGAE0B,gBAAuB,SAAS,CACzD;GAEP,MAAM,kBACJ,cAAc,YAAY,SACtB,SACA,wBAAwB,cAAc,QAAQ;GACpD,MAAM,iBACJ,cAAc,WAAW,SACrB,SACA,wBAAwB,cAAc,OAAc;AAE1D,UAAO;IACL,OAAO;IACP;IACA,UAAU,IAAI;IACd;IACA;IACA;IACD;IACD;KAEH,aAAa;EACZ,MAAM,2BAAW,IAAI,KAAa;EAClC,MAAM,WAID,EAAE;AAEP,OAAK,MAAM,SAAS,UAAU;GAC5B,MAAM,cACJ,MAAM,mBACL,OAAO,aAAa,cAAc,WAAW;AAEhD,OAAI,CAAC,YACH;GAGF,MAAM,kBAAkB,GAAG,MAAM,MAAM,GAAG,MAAM;AAChD,YAAS,IAAI,gBAAgB;AAC7B,YAAS,KAAK;IAAE;IAAiB;IAAO;IAAa,CAAC;;AAGxD,OAAK,MAAM,CAAC,KAAK,WAAW,CAAC,GAAG,cAAc,SAAS,CAAC,CACtD,KAAI,CAAC,SAAS,IAAI,IAAI,EAAE;AACtB,OAAI,OAAO,OAAO,SAChB,QAAO,OAAO,YAAY;AAE5B,iBAAc,OAAO,IAAI;;AAI7B,OAAK,MAAM,EAAE,iBAAiB,OAAO,iBAAiB,UAAU;GAC9D,MAAM,WAAW,cAAc,IAAI,gBAAgB;AACnD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,aAAa;AAChE,aAAS,OAAO,WAAW,MAAM;IACjC,MAAM,EACJ,QAAQ,SACR,SAAS,UACT,GAAG,gBACD,MAAM;IACV,MAAM,uBAAuB;KAC3B,GAAG;KACH,GAAI,MAAM,oBAAoB,SAC1B,EAAE,GACF,EAAE,SAAS,MAAM,iBAAiB;KACvC;AACD,aAAS,OAAO,WAAW,qBAAqB;AAChD;;AAGF,OAAI,UAAU;AACZ,QAAI,SAAS,OAAO,SAClB,UAAS,OAAO,YAAY;AAE9B,kBAAc,OAAO,gBAAgB;;GAGvC,MAAM,EACJ,QAAQ,SACR,SAAS,UACT,GAAG,gBACD,MAAM;GACV,MAAM,uBAAuB;IAC3B,GAAG;IACH,GAAI,MAAM,oBAAoB,SAC1B,EAAE,GACF,EAAE,SAAS,MAAM,iBAAiB;IACvC;GAED,MAAM,SAAS,QAAQ,SAAS,MAAM,cAAc,MAAM,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,iBAAc,IAAI,iBAAiB;IAAE;IAAQ,QAAQ;IAAa,CAAC;;IAGvE,EAAE,WAAW,MAAM,CACpB;AAED,4BAAkB;AAChB,eAAa;AACb,OAAK,MAAM,EAAE,YAAY,cAAc,QAAQ,CAC7C,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,gBAAc,OAAO;GACrB;;AAGJ,SAAS,wBAA2B,OAA+B;AACjE,QAAO,OAAO,UAAU,aAAc,OAAmB,kBAAS,MAAM"}

package/dist/useHotkeys.d.cts

@@ -0,0 +1,65 @@
+import { UseHotkeyOptions } from "./useHotkey.cjs";
+import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/useHotkeys.d.ts
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+interface UseHotkeyDefinition {
+  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+  hotkey: MaybeRefOrGetter<RegisterableHotkey>;
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback;
+  /** Per-hotkey options (merged on top of commonOptions) */
+  options?: MaybeRefOrGetter<UseHotkeyOptions>;
+}
+/**
+ * Vue composable for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * @param hotkeys - Array of hotkey definitions to register, or a getter/ref
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useHotkeys } from '@tanstack/vue-hotkeys'
+ *
+ * useHotkeys([
+ *   { hotkey: 'Mod+S', callback: () => save() },
+ *   { hotkey: 'Mod+Z', callback: () => undo() },
+ *   { hotkey: 'Escape', callback: () => close() },
+ * ])
+ * </script>
+ * ```
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { computed } from 'vue'
+ * import { useHotkeys } from '@tanstack/vue-hotkeys'
+ *
+ * const items = computed(() => [...])
+ * // Dynamic hotkeys from reactive data
+ * useHotkeys(
+ *   () => items.value.map((item) => ({
+ *     hotkey: item.shortcut,
+ *     callback: item.action,
+ *     options: { enabled: item.enabled },
+ *   })),
+ *   { preventDefault: true },
+ * )
+ * </script>
+ * ```
+ */
+declare function useHotkeys(hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>, commonOptions?: MaybeRefOrGetter<UseHotkeyOptions>): void;
+//#endregion
+export { UseHotkeyDefinition, useHotkeys };
+//# sourceMappingURL=useHotkeys.d.cts.map

package/dist/useHotkeys.d.ts

@@ -0,0 +1,65 @@
+import { UseHotkeyOptions } from "./useHotkey.js";
+import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/useHotkeys.d.ts
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+interface UseHotkeyDefinition {
+  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+  hotkey: MaybeRefOrGetter<RegisterableHotkey>;
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback;
+  /** Per-hotkey options (merged on top of commonOptions) */
+  options?: MaybeRefOrGetter<UseHotkeyOptions>;
+}
+/**
+ * Vue composable for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * @param hotkeys - Array of hotkey definitions to register, or a getter/ref
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useHotkeys } from '@tanstack/vue-hotkeys'
+ *
+ * useHotkeys([
+ *   { hotkey: 'Mod+S', callback: () => save() },
+ *   { hotkey: 'Mod+Z', callback: () => undo() },
+ *   { hotkey: 'Escape', callback: () => close() },
+ * ])
+ * </script>
+ * ```
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { computed } from 'vue'
+ * import { useHotkeys } from '@tanstack/vue-hotkeys'
+ *
+ * const items = computed(() => [...])
+ * // Dynamic hotkeys from reactive data
+ * useHotkeys(
+ *   () => items.value.map((item) => ({
+ *     hotkey: item.shortcut,
+ *     callback: item.action,
+ *     options: { enabled: item.enabled },
+ *   })),
+ *   { preventDefault: true },
+ * )
+ * </script>
+ * ```
+ */
+declare function useHotkeys(hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>, commonOptions?: MaybeRefOrGetter<UseHotkeyOptions>): void;
+//#endregion
+export { UseHotkeyDefinition, useHotkeys };
+//# sourceMappingURL=useHotkeys.d.ts.map

package/dist/useHotkeys.js

@@ -0,0 +1,140 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProviderContext.js";
+import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey } from "@tanstack/hotkeys";
+import { onUnmounted, unref, watch } from "vue";
+
+//#region src/useHotkeys.ts
+/**
+* Vue composable for registering multiple keyboard hotkeys at once.
+*
+* Uses the singleton HotkeyManager for efficient event handling.
+* Accepts a dynamic array of hotkey definitions, making it safe to use
+* with variable-length lists.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* @param hotkeys - Array of hotkey definitions to register, or a getter/ref
+* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+*
+* @example
+* ```vue
+* <script setup>
+* import { useHotkeys } from '@tanstack/vue-hotkeys'
+*
+* useHotkeys([
+*   { hotkey: 'Mod+S', callback: () => save() },
+*   { hotkey: 'Mod+Z', callback: () => undo() },
+*   { hotkey: 'Escape', callback: () => close() },
+* ])
+* <\/script>
+* ```
+*
+* @example
+* ```vue
+* <script setup>
+* import { computed } from 'vue'
+* import { useHotkeys } from '@tanstack/vue-hotkeys'
+*
+* const items = computed(() => [...])
+* // Dynamic hotkeys from reactive data
+* useHotkeys(
+*   () => items.value.map((item) => ({
+*     hotkey: item.shortcut,
+*     callback: item.action,
+*     options: { enabled: item.enabled },
+*   })),
+*   { preventDefault: true },
+* )
+* <\/script>
+* ```
+*/
+function useHotkeys(hotkeys, commonOptions = {}) {
+	const defaultOptions = useDefaultHotkeysOptions();
+	const manager = getHotkeyManager();
+	const registrations = /* @__PURE__ */ new Map();
+	const stopWatcher = watch(() => {
+		const resolvedHotkeys = resolveMaybeRefOrGetter(hotkeys);
+		const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions);
+		return resolvedHotkeys.map((def, i) => {
+			const resolvedHotkey = resolveMaybeRefOrGetter(def.hotkey);
+			const resolvedDefOptions = def.options ? resolveMaybeRefOrGetter(def.options) : {};
+			const mergedOptions = {
+				...defaultOptions.hotkey,
+				...resolvedCommonOptions,
+				...resolvedDefOptions
+			};
+			const platform = mergedOptions.platform ?? detectPlatform();
+			const hotkeyString = typeof resolvedHotkey === "string" ? resolvedHotkey : formatHotkey(rawHotkeyToParsedHotkey(resolvedHotkey, platform));
+			const resolvedEnabled = mergedOptions.enabled === void 0 ? void 0 : resolveMaybeRefOrGetter(mergedOptions.enabled);
+			const resolvedTarget = mergedOptions.target === void 0 ? void 0 : resolveMaybeRefOrGetter(mergedOptions.target);
+			return {
+				index: i,
+				hotkeyString,
+				callback: def.callback,
+				mergedOptions,
+				resolvedEnabled,
+				resolvedTarget
+			};
+		});
+	}, (resolved) => {
+		const nextKeys = /* @__PURE__ */ new Set();
+		const prepared = [];
+		for (const entry of resolved) {
+			const finalTarget = entry.resolvedTarget ?? (typeof document !== "undefined" ? document : null);
+			if (!finalTarget) continue;
+			const registrationKey = `${entry.index}:${entry.hotkeyString}`;
+			nextKeys.add(registrationKey);
+			prepared.push({
+				registrationKey,
+				entry,
+				finalTarget
+			});
+		}
+		for (const [key, record] of [...registrations.entries()]) if (!nextKeys.has(key)) {
+			if (record.handle.isActive) record.handle.unregister();
+			registrations.delete(key);
+		}
+		for (const { registrationKey, entry, finalTarget } of prepared) {
+			const existing = registrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === finalTarget) {
+				existing.handle.callback = entry.callback;
+				const { target: _target, enabled: _enabled, ...restOptions } = entry.mergedOptions;
+				const optionsWithoutTarget = {
+					...restOptions,
+					...entry.resolvedEnabled === void 0 ? {} : { enabled: entry.resolvedEnabled }
+				};
+				existing.handle.setOptions(optionsWithoutTarget);
+				continue;
+			}
+			if (existing) {
+				if (existing.handle.isActive) existing.handle.unregister();
+				registrations.delete(registrationKey);
+			}
+			const { target: _target, enabled: _enabled, ...restOptions } = entry.mergedOptions;
+			const optionsWithoutTarget = {
+				...restOptions,
+				...entry.resolvedEnabled === void 0 ? {} : { enabled: entry.resolvedEnabled }
+			};
+			const handle = manager.register(entry.hotkeyString, entry.callback, {
+				...optionsWithoutTarget,
+				target: finalTarget
+			});
+			registrations.set(registrationKey, {
+				handle,
+				target: finalTarget
+			});
+		}
+	}, { immediate: true });
+	onUnmounted(() => {
+		stopWatcher();
+		for (const { handle } of registrations.values()) if (handle.isActive) handle.unregister();
+		registrations.clear();
+	});
+}
+function resolveMaybeRefOrGetter(value) {
+	return typeof value === "function" ? value() : unref(value);
+}
+
+//#endregion
+export { useHotkeys };
+//# sourceMappingURL=useHotkeys.js.map

package/dist/useHotkeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeys.js","names":[],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { onUnmounted, unref, watch } from 'vue'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProviderContext'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport type { MaybeRefOrGetter } from 'vue'\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: MaybeRefOrGetter<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?: MaybeRefOrGetter<UseHotkeyOptions>\n}\n\n/**\n * Vue composable 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.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * @param hotkeys - Array of hotkey definitions to register, or a getter/ref\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)\n *\n * @example\n * ```vue\n * <script setup>\n * import { useHotkeys } from '@tanstack/vue-hotkeys'\n *\n * useHotkeys([\n *   { hotkey: 'Mod+S', callback: () => save() },\n *   { hotkey: 'Mod+Z', callback: () => undo() },\n *   { hotkey: 'Escape', callback: () => close() },\n * ])\n * </script>\n * ```\n *\n * @example\n * ```vue\n * <script setup>\n * import { computed } from 'vue'\n * import { useHotkeys } from '@tanstack/vue-hotkeys'\n *\n * const items = computed(() => [...])\n * // Dynamic hotkeys from reactive data\n * useHotkeys(\n *   () => items.value.map((item) => ({\n *     hotkey: item.shortcut,\n *     callback: item.action,\n *     options: { enabled: item.enabled },\n *   })),\n *   { preventDefault: true },\n * )\n * </script>\n * ```\n */\nexport function useHotkeys(\n  hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>,\n  commonOptions: MaybeRefOrGetter<UseHotkeyOptions> = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions()\n  const manager = getHotkeyManager()\n\n  const registrations = new Map<string, RegistrationRecord>()\n\n  const stopWatcher = watch(\n    () => {\n      const resolvedHotkeys = resolveMaybeRefOrGetter(hotkeys)\n      const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions)\n\n      return resolvedHotkeys.map((def, i) => {\n        const resolvedHotkey = resolveMaybeRefOrGetter(def.hotkey)\n        const resolvedDefOptions = def.options\n          ? resolveMaybeRefOrGetter(def.options)\n          : {}\n\n        const mergedOptions = {\n          ...defaultOptions.hotkey,\n          ...resolvedCommonOptions,\n          ...resolvedDefOptions,\n        } as UseHotkeyOptions\n\n        const platform = mergedOptions.platform ?? detectPlatform()\n        const hotkeyString: Hotkey =\n          typeof resolvedHotkey === 'string'\n            ? resolvedHotkey\n            : (formatHotkey(\n                rawHotkeyToParsedHotkey(resolvedHotkey as any, platform),\n              ) as Hotkey)\n\n        const resolvedEnabled =\n          mergedOptions.enabled === undefined\n            ? undefined\n            : resolveMaybeRefOrGetter(mergedOptions.enabled)\n        const resolvedTarget =\n          mergedOptions.target === undefined\n            ? undefined\n            : resolveMaybeRefOrGetter(mergedOptions.target as any)\n\n        return {\n          index: i,\n          hotkeyString,\n          callback: def.callback,\n          mergedOptions,\n          resolvedEnabled,\n          resolvedTarget,\n        }\n      })\n    },\n    (resolved) => {\n      const nextKeys = new Set<string>()\n      const prepared: Array<{\n        registrationKey: string\n        entry: (typeof resolved)[number]\n        finalTarget: Document | HTMLElement | Window\n      }> = []\n\n      for (const entry of resolved) {\n        const finalTarget =\n          entry.resolvedTarget ??\n          (typeof document !== 'undefined' ? document : null)\n\n        if (!finalTarget) {\n          continue\n        }\n\n        const registrationKey = `${entry.index}:${entry.hotkeyString}`\n        nextKeys.add(registrationKey)\n        prepared.push({ registrationKey, entry, finalTarget })\n      }\n\n      for (const [key, record] of [...registrations.entries()]) {\n        if (!nextKeys.has(key)) {\n          if (record.handle.isActive) {\n            record.handle.unregister()\n          }\n          registrations.delete(key)\n        }\n      }\n\n      for (const { registrationKey, entry, finalTarget } of prepared) {\n        const existing = registrations.get(registrationKey)\n        if (existing?.handle.isActive && existing.target === finalTarget) {\n          existing.handle.callback = entry.callback\n          const {\n            target: _target,\n            enabled: _enabled,\n            ...restOptions\n          } = entry.mergedOptions\n          const optionsWithoutTarget = {\n            ...restOptions,\n            ...(entry.resolvedEnabled === undefined\n              ? {}\n              : { enabled: entry.resolvedEnabled }),\n          }\n          existing.handle.setOptions(optionsWithoutTarget)\n          continue\n        }\n\n        if (existing) {\n          if (existing.handle.isActive) {\n            existing.handle.unregister()\n          }\n          registrations.delete(registrationKey)\n        }\n\n        const {\n          target: _target,\n          enabled: _enabled,\n          ...restOptions\n        } = entry.mergedOptions\n        const optionsWithoutTarget = {\n          ...restOptions,\n          ...(entry.resolvedEnabled === undefined\n            ? {}\n            : { enabled: entry.resolvedEnabled }),\n        }\n\n        const handle = manager.register(entry.hotkeyString, entry.callback, {\n          ...optionsWithoutTarget,\n          target: finalTarget,\n        })\n        registrations.set(registrationKey, { handle, target: finalTarget })\n      }\n    },\n    { immediate: true },\n  )\n\n  onUnmounted(() => {\n    stopWatcher()\n    for (const { handle } of registrations.values()) {\n      if (handle.isActive) {\n        handle.unregister()\n      }\n    }\n    registrations.clear()\n  })\n}\n\nfunction resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {\n  return typeof value === 'function' ? (value as () => T)() : unref(value)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-hotkeys",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Vue adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -46,9 +46,9 @@
     "@tanstack/hotkeys": "0.4.2"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^6.0.4",
+    "@vitejs/plugin-vue": "^6.0.5",
     "@vue/test-utils": "^2.4.6",
-    "vue": "^3.5.29"
+    "vue": "^3.5.30"
   },
   "peerDependencies": {
     "vue": ">=3.0.0"

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './HotkeysProviderContext'
 
 // Vue-specific composables
 export * from './useHotkey'
+export * from './useHotkeys'
 export * from './useHeldKeys'
 export * from './useHeldKeyCodes'
 export * from './useKeyHold'

package/src/useHotkeys.ts

@@ -0,0 +1,225 @@
+import { onUnmounted, unref, watch } from 'vue'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
+import type { UseHotkeyOptions } from './useHotkey'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyRegistrationHandle,
+  RegisterableHotkey,
+} from '@tanstack/hotkeys'
+import type { MaybeRefOrGetter } from 'vue'
+
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+export interface UseHotkeyDefinition {
+  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+  hotkey: MaybeRefOrGetter<RegisterableHotkey>
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback
+  /** Per-hotkey options (merged on top of commonOptions) */
+  options?: MaybeRefOrGetter<UseHotkeyOptions>
+}
+
+/**
+ * Vue composable for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * @param hotkeys - Array of hotkey definitions to register, or a getter/ref
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useHotkeys } from '@tanstack/vue-hotkeys'
+ *
+ * useHotkeys([
+ *   { hotkey: 'Mod+S', callback: () => save() },
+ *   { hotkey: 'Mod+Z', callback: () => undo() },
+ *   { hotkey: 'Escape', callback: () => close() },
+ * ])
+ * </script>
+ * ```
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { computed } from 'vue'
+ * import { useHotkeys } from '@tanstack/vue-hotkeys'
+ *
+ * const items = computed(() => [...])
+ * // Dynamic hotkeys from reactive data
+ * useHotkeys(
+ *   () => items.value.map((item) => ({
+ *     hotkey: item.shortcut,
+ *     callback: item.action,
+ *     options: { enabled: item.enabled },
+ *   })),
+ *   { preventDefault: true },
+ * )
+ * </script>
+ * ```
+ */
+export function useHotkeys(
+  hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>,
+  commonOptions: MaybeRefOrGetter<UseHotkeyOptions> = {},
+): void {
+  type RegistrationRecord = {
+    handle: HotkeyRegistrationHandle
+    target: Document | HTMLElement | Window
+  }
+
+  const defaultOptions = useDefaultHotkeysOptions()
+  const manager = getHotkeyManager()
+
+  const registrations = new Map<string, RegistrationRecord>()
+
+  const stopWatcher = watch(
+    () => {
+      const resolvedHotkeys = resolveMaybeRefOrGetter(hotkeys)
+      const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions)
+
+      return resolvedHotkeys.map((def, i) => {
+        const resolvedHotkey = resolveMaybeRefOrGetter(def.hotkey)
+        const resolvedDefOptions = def.options
+          ? resolveMaybeRefOrGetter(def.options)
+          : {}
+
+        const mergedOptions = {
+          ...defaultOptions.hotkey,
+          ...resolvedCommonOptions,
+          ...resolvedDefOptions,
+        } as UseHotkeyOptions
+
+        const platform = mergedOptions.platform ?? detectPlatform()
+        const hotkeyString: Hotkey =
+          typeof resolvedHotkey === 'string'
+            ? resolvedHotkey
+            : (formatHotkey(
+                rawHotkeyToParsedHotkey(resolvedHotkey as any, platform),
+              ) as Hotkey)
+
+        const resolvedEnabled =
+          mergedOptions.enabled === undefined
+            ? undefined
+            : resolveMaybeRefOrGetter(mergedOptions.enabled)
+        const resolvedTarget =
+          mergedOptions.target === undefined
+            ? undefined
+            : resolveMaybeRefOrGetter(mergedOptions.target as any)
+
+        return {
+          index: i,
+          hotkeyString,
+          callback: def.callback,
+          mergedOptions,
+          resolvedEnabled,
+          resolvedTarget,
+        }
+      })
+    },
+    (resolved) => {
+      const nextKeys = new Set<string>()
+      const prepared: Array<{
+        registrationKey: string
+        entry: (typeof resolved)[number]
+        finalTarget: Document | HTMLElement | Window
+      }> = []
+
+      for (const entry of resolved) {
+        const finalTarget =
+          entry.resolvedTarget ??
+          (typeof document !== 'undefined' ? document : null)
+
+        if (!finalTarget) {
+          continue
+        }
+
+        const registrationKey = `${entry.index}:${entry.hotkeyString}`
+        nextKeys.add(registrationKey)
+        prepared.push({ registrationKey, entry, finalTarget })
+      }
+
+      for (const [key, record] of [...registrations.entries()]) {
+        if (!nextKeys.has(key)) {
+          if (record.handle.isActive) {
+            record.handle.unregister()
+          }
+          registrations.delete(key)
+        }
+      }
+
+      for (const { registrationKey, entry, finalTarget } of prepared) {
+        const existing = registrations.get(registrationKey)
+        if (existing?.handle.isActive && existing.target === finalTarget) {
+          existing.handle.callback = entry.callback
+          const {
+            target: _target,
+            enabled: _enabled,
+            ...restOptions
+          } = entry.mergedOptions
+          const optionsWithoutTarget = {
+            ...restOptions,
+            ...(entry.resolvedEnabled === undefined
+              ? {}
+              : { enabled: entry.resolvedEnabled }),
+          }
+          existing.handle.setOptions(optionsWithoutTarget)
+          continue
+        }
+
+        if (existing) {
+          if (existing.handle.isActive) {
+            existing.handle.unregister()
+          }
+          registrations.delete(registrationKey)
+        }
+
+        const {
+          target: _target,
+          enabled: _enabled,
+          ...restOptions
+        } = entry.mergedOptions
+        const optionsWithoutTarget = {
+          ...restOptions,
+          ...(entry.resolvedEnabled === undefined
+            ? {}
+            : { enabled: entry.resolvedEnabled }),
+        }
+
+        const handle = manager.register(entry.hotkeyString, entry.callback, {
+          ...optionsWithoutTarget,
+          target: finalTarget,
+        })
+        registrations.set(registrationKey, { handle, target: finalTarget })
+      }
+    },
+    { immediate: true },
+  )
+
+  onUnmounted(() => {
+    stopWatcher()
+    for (const { handle } of registrations.values()) {
+      if (handle.isActive) {
+        handle.unregister()
+      }
+    }
+    registrations.clear()
+  })
+}
+
+function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
+  return typeof value === 'function' ? (value as () => T)() : unref(value)
+}