@tanstack/svelte-hotkeys 0.6.0 → 0.8.0

package/README.md

@@ -37,7 +37,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is pre-alpha (prototyping phase). We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
 
 Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
 

package/dist/createHotkey.svelte.js

@@ -1,20 +1,9 @@
-import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey, } from '@tanstack/hotkeys';
+import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey, } from '@tanstack/hotkeys';
+import { onDestroy } from 'svelte';
 import { getDefaultHotkeysOptions } from './HotkeysCtx';
 import { resolveMaybeGetter } from './internal.svelte';
-function normalizeHotkey(hotkey, options) {
-    const platform = options.platform ?? detectPlatform();
-    return typeof hotkey === 'string'
-        ? hotkey
-        : formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform));
-}
-function registerHotkey(target, hotkey, callback, options) {
-    const resolvedHotkey = resolveMaybeGetter(hotkey);
-    const resolvedOptions = resolveMaybeGetter(options);
-    const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkey,
-        ...resolvedOptions,
-    };
-    return getHotkeyManager().register(normalizeHotkey(resolvedHotkey, mergedOptions), callback, {
+function registerHotkey(target, hotkey, callback, mergedOptions) {
+    return getHotkeyManager().register(normalizeRegisterableHotkey(hotkey, mergedOptions.platform ?? detectPlatform()), callback, {
         ...mergedOptions,
         target,
     });
@@ -34,14 +23,37 @@ function registerHotkey(target, hotkey, callback, options) {
  * ```
  */
 export function createHotkey(hotkey, callback, options = {}) {
+    let registration = null;
+    let lastHotkeyStr = null;
     $effect(() => {
         if (typeof document === 'undefined') {
             return;
         }
-        const registration = registerHotkey(document, hotkey, callback, options);
-        return () => {
-            registration.unregister();
+        const resolvedHotkey = resolveMaybeGetter(hotkey);
+        const resolvedOptions = resolveMaybeGetter(options);
+        const mergedOptions = {
+            ...getDefaultHotkeysOptions().hotkey,
+            ...resolvedOptions,
         };
+        const hotkeyStr = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
+        const { target: _t, ...optionsWithoutTarget } = mergedOptions;
+        if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
+            registration.callback = callback;
+            registration.setOptions(optionsWithoutTarget);
+            return;
+        }
+        if (registration?.isActive) {
+            registration.unregister();
+            registration = null;
+        }
+        registration = registerHotkey(document, resolvedHotkey, callback, mergedOptions);
+        lastHotkeyStr = hotkeyStr;
+    });
+    onDestroy(() => {
+        if (registration?.isActive) {
+            registration.unregister();
+            registration = null;
+        }
     });
 }
 /**
@@ -67,11 +79,27 @@ export function createHotkey(hotkey, callback, options = {}) {
 export function createHotkeyAttachment(hotkey, callback, options = {}) {
     return (element) => {
         let registration = null;
+        let lastHotkeyStr = null;
         $effect(() => {
+            const resolvedHotkey = resolveMaybeGetter(hotkey);
+            const resolvedOptions = resolveMaybeGetter(options);
+            const mergedOptions = {
+                ...getDefaultHotkeysOptions().hotkey,
+                ...resolvedOptions,
+            };
+            const hotkeyStr = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
+            const { target: _t, ...optionsWithoutTarget } = mergedOptions;
+            if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
+                registration.callback = callback;
+                registration.setOptions(optionsWithoutTarget);
+                return;
+            }
             if (registration?.isActive) {
                 registration.unregister();
+                registration = null;
             }
-            registration = registerHotkey(element, hotkey, callback, options);
+            registration = registerHotkey(element, resolvedHotkey, callback, mergedOptions);
+            lastHotkeyStr = hotkeyStr;
         });
         return () => {
             if (registration?.isActive) {

package/dist/createHotkeySequence.svelte.js

@@ -1,14 +1,9 @@
-import { getSequenceManager } from '@tanstack/hotkeys';
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
+import { onDestroy } from 'svelte';
 import { getDefaultHotkeysOptions } from './HotkeysCtx';
 import { resolveMaybeGetter } from './internal.svelte';
-function registerHotkeySequence(target, sequence, callback, options) {
-    const resolvedSequence = resolveMaybeGetter(sequence);
-    const resolvedOptions = resolveMaybeGetter(options);
-    const mergedOptions = {
-        ...getDefaultHotkeysOptions().hotkeySequence,
-        ...resolvedOptions,
-    };
-    return getSequenceManager().register(resolvedSequence, callback, {
+function registerHotkeySequence(target, sequence, callback, mergedOptions) {
+    return getSequenceManager().register(sequence, callback, {
         ...mergedOptions,
         target,
     });
@@ -53,18 +48,45 @@ function registerHotkeySequence(target, sequence, callback, options) {
  * ```
  */
 export function createHotkeySequence(sequence, callback, options = {}) {
+    let registration = null;
+    let lastSequenceKey = null;
     $effect(() => {
         if (typeof document === 'undefined') {
             return;
         }
         const resolvedSequence = resolveMaybeGetter(sequence);
+        const resolvedOptions = resolveMaybeGetter(options);
+        const mergedOptions = {
+            ...getDefaultHotkeysOptions().hotkeySequence,
+            ...resolvedOptions,
+        };
+        const { target: _t, ...optionsWithoutTarget } = mergedOptions;
         if (resolvedSequence.length === 0) {
+            if (registration?.isActive) {
+                registration.unregister();
+                registration = null;
+            }
+            lastSequenceKey = null;
             return;
         }
-        const registration = registerHotkeySequence(document, resolvedSequence, callback, options);
-        return () => {
+        const sequenceKey = formatHotkeySequence(resolvedSequence);
+        if (registration?.isActive && lastSequenceKey === sequenceKey) {
+            registration.callback = callback;
+            registration.setOptions(optionsWithoutTarget);
+            return;
+        }
+        if (registration?.isActive) {
             registration.unregister();
-        };
+            registration = null;
+        }
+        registration = registerHotkeySequence(document, resolvedSequence, callback, mergedOptions);
+        lastSequenceKey = sequenceKey;
+    });
+    onDestroy(() => {
+        if (registration?.isActive) {
+            registration.unregister();
+            registration = null;
+        }
     });
 }
 /**
@@ -88,16 +110,35 @@ export function createHotkeySequence(sequence, callback, options = {}) {
 export function createHotkeySequenceAttachment(sequence, callback, options = {}) {
     return (element) => {
         let registration = null;
+        let lastSequenceKey = null;
         $effect(() => {
             const resolvedSequence = resolveMaybeGetter(sequence);
+            const resolvedOptions = resolveMaybeGetter(options);
+            const mergedOptions = {
+                ...getDefaultHotkeysOptions().hotkeySequence,
+                ...resolvedOptions,
+            };
+            const { target: _t, ...optionsWithoutTarget } = mergedOptions;
+            if (resolvedSequence.length === 0) {
+                if (registration?.isActive) {
+                    registration.unregister();
+                    registration = null;
+                }
+                lastSequenceKey = null;
+                return;
+            }
+            const sequenceKey = formatHotkeySequence(resolvedSequence);
+            if (registration?.isActive && lastSequenceKey === sequenceKey) {
+                registration.callback = callback;
+                registration.setOptions(optionsWithoutTarget);
+                return;
+            }
             if (registration?.isActive) {
                 registration.unregister();
                 registration = null;
             }
-            if (resolvedSequence.length === 0) {
-                return;
-            }
-            registration = registerHotkeySequence(element, resolvedSequence, callback, options);
+            registration = registerHotkeySequence(element, resolvedSequence, callback, mergedOptions);
+            lastSequenceKey = sequenceKey;
         });
         return () => {
             if (registration?.isActive) {

package/dist/createHotkeySequences.svelte.d.ts

@@ -0,0 +1,49 @@
+import type { HotkeyCallback, HotkeySequence } from '@tanstack/hotkeys';
+import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte';
+import type { MaybeGetter } from './internal.svelte';
+import type { Attachment } from 'svelte/attachments';
+/**
+ * A single sequence definition for use with `createHotkeySequences`.
+ */
+export interface CreateHotkeySequenceDefinition {
+    /** Array of hotkey strings that form the sequence */
+    sequence: MaybeGetter<HotkeySequence>;
+    /** The function to call when the sequence is completed */
+    callback: HotkeyCallback;
+    /** Per-sequence options (merged on top of commonOptions) */
+    options?: MaybeGetter<CreateHotkeySequenceOptions>;
+}
+/**
+ * Register multiple global keyboard shortcut sequences for the current component.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createHotkeySequences } from '@tanstack/svelte-hotkeys'
+ *
+ *   createHotkeySequences([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *   ])
+ * </script>
+ * ```
+ */
+export declare function createHotkeySequences(definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>, commonOptions?: MaybeGetter<CreateHotkeySequenceOptions>): void;
+/**
+ * Create an attachment for element-scoped multi-sequence registration.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createHotkeySequencesAttachment } from '@tanstack/svelte-hotkeys'
+ *
+ *   const vim = createHotkeySequencesAttachment([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *   ])
+ * </script>
+ *
+ * <div tabindex="0" {@attach vim}>Editor</div>
+ * ```
+ */
+export declare function createHotkeySequencesAttachment(definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>, commonOptions?: MaybeGetter<CreateHotkeySequenceOptions>): Attachment<HTMLElement>;

package/dist/createHotkeySequences.svelte.js

@@ -0,0 +1,189 @@
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
+import { onDestroy } from 'svelte';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { getDefaultHotkeysOptions } from './HotkeysCtx';
+import { resolveMaybeGetter } from './internal.svelte';
+function cleanupRegistrations(registrations) {
+    for (const { handle } of registrations.values()) {
+        if (handle.isActive) {
+            handle.unregister();
+        }
+    }
+    registrations.clear();
+}
+/**
+ * Register multiple global keyboard shortcut sequences for the current component.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createHotkeySequences } from '@tanstack/svelte-hotkeys'
+ *
+ *   createHotkeySequences([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *   ])
+ * </script>
+ * ```
+ */
+export function createHotkeySequences(definitions, commonOptions = {}) {
+    const registrations = new SvelteMap();
+    onDestroy(() => {
+        cleanupRegistrations(registrations);
+    });
+    $effect(() => {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        const resolvedDefinitions = resolveMaybeGetter(definitions);
+        const resolvedCommonOptions = resolveMaybeGetter(commonOptions);
+        const nextKeys = new SvelteSet();
+        const prepared = [];
+        for (let i = 0; i < resolvedDefinitions.length; i++) {
+            const def = resolvedDefinitions[i];
+            const resolvedSequence = resolveMaybeGetter(def.sequence);
+            if (resolvedSequence.length === 0) {
+                continue;
+            }
+            const resolvedDefOptions = def.options
+                ? resolveMaybeGetter(def.options)
+                : {};
+            const mergedOptions = {
+                ...getDefaultHotkeysOptions().hotkeySequence,
+                ...resolvedCommonOptions,
+                ...resolvedDefOptions,
+            };
+            const resolvedTarget = mergedOptions.target ??
+                (typeof document !== 'undefined' ? document : null);
+            if (!resolvedTarget) {
+                continue;
+            }
+            const sequenceString = formatHotkeySequence(resolvedSequence);
+            const registrationKey = `${i}:${sequenceString}`;
+            nextKeys.add(registrationKey);
+            prepared.push({
+                registrationKey,
+                def,
+                mergedOptions,
+                sequenceString,
+                resolvedSequence,
+                resolvedTarget,
+            });
+        }
+        for (const [key, record] of [...registrations.entries()]) {
+            if (!nextKeys.has(key)) {
+                if (record.handle.isActive) {
+                    record.handle.unregister();
+                }
+                registrations.delete(key);
+            }
+        }
+        for (const p of prepared) {
+            const existing = registrations.get(p.registrationKey);
+            const { target: _target, ...optionsWithoutTarget } = p.mergedOptions;
+            if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
+                existing.handle.callback = p.def.callback;
+                existing.handle.setOptions(optionsWithoutTarget);
+                continue;
+            }
+            if (existing?.handle.isActive) {
+                existing.handle.unregister();
+            }
+            if (existing) {
+                registrations.delete(p.registrationKey);
+            }
+            const handle = getSequenceManager().register(p.resolvedSequence, p.def.callback, {
+                ...optionsWithoutTarget,
+                target: p.resolvedTarget,
+            });
+            registrations.set(p.registrationKey, {
+                handle,
+                target: p.resolvedTarget,
+            });
+        }
+    });
+}
+/**
+ * Create an attachment for element-scoped multi-sequence registration.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createHotkeySequencesAttachment } from '@tanstack/svelte-hotkeys'
+ *
+ *   const vim = createHotkeySequencesAttachment([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *   ])
+ * </script>
+ *
+ * <div tabindex="0" {@attach vim}>Editor</div>
+ * ```
+ */
+export function createHotkeySequencesAttachment(definitions, commonOptions = {}) {
+    return (element) => {
+        const registrations = new SvelteMap();
+        $effect(() => {
+            const resolvedDefinitions = resolveMaybeGetter(definitions);
+            const resolvedCommonOptions = resolveMaybeGetter(commonOptions);
+            const nextKeys = new SvelteSet();
+            const prepared = [];
+            for (let i = 0; i < resolvedDefinitions.length; i++) {
+                const def = resolvedDefinitions[i];
+                const resolvedSequence = resolveMaybeGetter(def.sequence);
+                if (resolvedSequence.length === 0) {
+                    continue;
+                }
+                const resolvedDefOptions = def.options
+                    ? resolveMaybeGetter(def.options)
+                    : {};
+                const mergedOptions = {
+                    ...getDefaultHotkeysOptions().hotkeySequence,
+                    ...resolvedCommonOptions,
+                    ...resolvedDefOptions,
+                };
+                const sequenceString = formatHotkeySequence(resolvedSequence);
+                const registrationKey = `${i}:${sequenceString}`;
+                nextKeys.add(registrationKey);
+                prepared.push({
+                    registrationKey,
+                    def,
+                    mergedOptions,
+                    sequenceString,
+                    resolvedSequence,
+                });
+            }
+            for (const [key, record] of [...registrations.entries()]) {
+                if (!nextKeys.has(key)) {
+                    if (record.handle.isActive) {
+                        record.handle.unregister();
+                    }
+                    registrations.delete(key);
+                }
+            }
+            for (const p of prepared) {
+                const existing = registrations.get(p.registrationKey);
+                const { target: _target, ...optionsWithoutTarget } = p.mergedOptions;
+                if (existing?.handle.isActive && existing.target === element) {
+                    existing.handle.callback = p.def.callback;
+                    existing.handle.setOptions(optionsWithoutTarget);
+                    continue;
+                }
+                if (existing?.handle.isActive) {
+                    existing.handle.unregister();
+                }
+                if (existing) {
+                    registrations.delete(p.registrationKey);
+                }
+                const handle = getSequenceManager().register(p.resolvedSequence, p.def.callback, {
+                    ...optionsWithoutTarget,
+                    target: element,
+                });
+                registrations.set(p.registrationKey, { handle, target: element });
+            }
+        });
+        return () => {
+            cleanupRegistrations(registrations);
+        };
+    };
+}

package/dist/createHotkeys.svelte.js

@@ -1,14 +1,8 @@
-import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey, } from '@tanstack/hotkeys';
+import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey, } from '@tanstack/hotkeys';
 import { onDestroy } from 'svelte';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { getDefaultHotkeysOptions } from './HotkeysCtx';
 import { resolveMaybeGetter } from './internal.svelte';
-function normalizeHotkey(hotkey, options) {
-    const platform = options.platform ?? detectPlatform();
-    return typeof hotkey === 'string'
-        ? hotkey
-        : formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform));
-}
 function cleanupRegistrations(registrations) {
     for (const { handle } of registrations.values()) {
         if (handle.isActive) {
@@ -62,7 +56,7 @@ export function createHotkeys(hotkeys, commonOptions = {}) {
             if (!resolvedTarget) {
                 continue;
             }
-            const hotkeyString = normalizeHotkey(resolvedHotkey, mergedOptions);
+            const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
             const registrationKey = `${i}:${hotkeyString}`;
             nextKeys.add(registrationKey);
             prepared.push({
@@ -144,7 +138,7 @@ export function createHotkeysAttachment(hotkeys, commonOptions = {}) {
                     ...resolvedCommonOptions,
                     ...resolvedDefOptions,
                 };
-                const hotkeyString = normalizeHotkey(resolvedHotkey, mergedOptions);
+                const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
                 const registrationKey = `${i}:${hotkeyString}`;
                 nextKeys.add(registrationKey);
                 prepared.push({

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from '@tanstack/hotkeys';
 export * from './createHotkey.svelte';
 export * from './createHotkeys.svelte';
 export * from './createHotkeySequence.svelte';
+export * from './createHotkeySequences.svelte';
 export * from './createHotkeyRecorder.svelte';
 export * from './createHotkeySequenceRecorder.svelte';
 export * from './getHeldKeys.svelte';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from '@tanstack/hotkeys';
 export * from './createHotkey.svelte';
 export * from './createHotkeys.svelte';
 export * from './createHotkeySequence.svelte';
+export * from './createHotkeySequences.svelte';
 export * from './createHotkeyRecorder.svelte';
 export * from './createHotkeySequenceRecorder.svelte';
 export * from './getHeldKeys.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.5.0"
+    "@tanstack/hotkeys": "0.6.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",

package/src/createHotkey.svelte.ts

@@ -1,15 +1,16 @@
 import {
   detectPlatform,
-  formatHotkey,
   getHotkeyManager,
-  rawHotkeyToParsedHotkey,
+  normalizeRegisterableHotkey,
 } from '@tanstack/hotkeys'
+import { onDestroy } from 'svelte'
 import { getDefaultHotkeysOptions } from './HotkeysCtx'
 import { resolveMaybeGetter } from './internal.svelte'
 import type {
   Hotkey,
   HotkeyCallback,
   HotkeyOptions,
+  HotkeyRegistrationHandle,
   RegisterableHotkey,
 } from '@tanstack/hotkeys'
 import type { MaybeGetter } from './internal.svelte'
@@ -19,32 +20,17 @@ export interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
   target?: Document | Window // not html elements, use attachment instead
 }
 
-function normalizeHotkey(
-  hotkey: RegisterableHotkey,
-  options: CreateHotkeyOptions,
-): Hotkey {
-  const platform = options.platform ?? detectPlatform()
-
-  return typeof hotkey === 'string'
-    ? hotkey
-    : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)
-}
-
 function registerHotkey(
   target: HTMLElement | Document | Window,
-  hotkey: MaybeGetter<RegisterableHotkey>,
+  hotkey: RegisterableHotkey,
   callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeyOptions>,
+  mergedOptions: CreateHotkeyOptions,
 ) {
-  const resolvedHotkey = resolveMaybeGetter(hotkey)
-  const resolvedOptions = resolveMaybeGetter(options)
-  const mergedOptions = {
-    ...getDefaultHotkeysOptions().hotkey,
-    ...resolvedOptions,
-  } as CreateHotkeyOptions
-
   return getHotkeyManager().register(
-    normalizeHotkey(resolvedHotkey, mergedOptions),
+    normalizeRegisterableHotkey(
+      hotkey,
+      mergedOptions.platform ?? detectPlatform(),
+    ),
     callback,
     {
       ...mergedOptions,
@@ -72,15 +58,51 @@ export function createHotkey(
   callback: HotkeyCallback,
   options: MaybeGetter<CreateHotkeyOptions> = {},
 ): void {
+  let registration: HotkeyRegistrationHandle | null = null
+  let lastHotkeyStr: Hotkey | null = null
+
   $effect(() => {
     if (typeof document === 'undefined') {
       return
     }
 
-    const registration = registerHotkey(document, hotkey, callback, options)
+    const resolvedHotkey = resolveMaybeGetter(hotkey)
+    const resolvedOptions = resolveMaybeGetter(options)
+    const mergedOptions = {
+      ...getDefaultHotkeysOptions().hotkey,
+      ...resolvedOptions,
+    } as CreateHotkeyOptions
 
-    return () => {
+    const hotkeyStr = normalizeRegisterableHotkey(
+      resolvedHotkey,
+      mergedOptions.platform ?? detectPlatform(),
+    )
+    const { target: _t, ...optionsWithoutTarget } = mergedOptions
+
+    if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
+      registration.callback = callback
+      registration.setOptions(optionsWithoutTarget)
+      return
+    }
+
+    if (registration?.isActive) {
       registration.unregister()
+      registration = null
+    }
+
+    registration = registerHotkey(
+      document,
+      resolvedHotkey,
+      callback,
+      mergedOptions,
+    )
+    lastHotkeyStr = hotkeyStr
+  })
+
+  onDestroy(() => {
+    if (registration?.isActive) {
+      registration.unregister()
+      registration = null
     }
   })
 }
@@ -111,14 +133,41 @@ export function createHotkeyAttachment(
   options: MaybeGetter<CreateHotkeyOptions> = {},
 ): Attachment<HTMLElement> {
   return (element) => {
-    let registration: ReturnType<typeof registerHotkey> | null = null
+    let registration: HotkeyRegistrationHandle | null = null
+    let lastHotkeyStr: Hotkey | null = null
 
     $effect(() => {
+      const resolvedHotkey = resolveMaybeGetter(hotkey)
+      const resolvedOptions = resolveMaybeGetter(options)
+      const mergedOptions = {
+        ...getDefaultHotkeysOptions().hotkey,
+        ...resolvedOptions,
+      } as CreateHotkeyOptions
+
+      const hotkeyStr = normalizeRegisterableHotkey(
+        resolvedHotkey,
+        mergedOptions.platform ?? detectPlatform(),
+      )
+      const { target: _t, ...optionsWithoutTarget } = mergedOptions
+
+      if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
+        registration.callback = callback
+        registration.setOptions(optionsWithoutTarget)
+        return
+      }
+
       if (registration?.isActive) {
         registration.unregister()
+        registration = null
       }
 
-      registration = registerHotkey(element, hotkey, callback, options)
+      registration = registerHotkey(
+        element,
+        resolvedHotkey,
+        callback,
+        mergedOptions,
+      )
+      lastHotkeyStr = hotkeyStr
     })
 
     return () => {

package/src/createHotkeySequence.svelte.ts

@@ -1,10 +1,12 @@
-import { getSequenceManager } from '@tanstack/hotkeys'
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
+import { onDestroy } from 'svelte'
 import { getDefaultHotkeysOptions } from './HotkeysCtx'
 import { resolveMaybeGetter } from './internal.svelte'
 import type {
   HotkeyCallback,
   HotkeySequence,
   SequenceOptions,
+  SequenceRegistrationHandle,
 } from '@tanstack/hotkeys'
 import type { MaybeGetter } from './internal.svelte'
 import type { Attachment } from 'svelte/attachments'
@@ -18,18 +20,11 @@ export interface CreateHotkeySequenceOptions extends Omit<
 
 function registerHotkeySequence(
   target: HTMLElement | Document | Window,
-  sequence: MaybeGetter<HotkeySequence>,
+  sequence: HotkeySequence,
   callback: HotkeyCallback,
-  options: MaybeGetter<CreateHotkeySequenceOptions>,
+  mergedOptions: CreateHotkeySequenceOptions,
 ) {
-  const resolvedSequence = resolveMaybeGetter(sequence)
-  const resolvedOptions = resolveMaybeGetter(options)
-  const mergedOptions = {
-    ...getDefaultHotkeysOptions().hotkeySequence,
-    ...resolvedOptions,
-  } as CreateHotkeySequenceOptions
-
-  return getSequenceManager().register(resolvedSequence, callback, {
+  return getSequenceManager().register(sequence, callback, {
     ...mergedOptions,
     target,
   })
@@ -79,25 +74,58 @@ export function createHotkeySequence(
   callback: HotkeyCallback,
   options: MaybeGetter<CreateHotkeySequenceOptions> = {},
 ): void {
+  let registration: SequenceRegistrationHandle | null = null
+  let lastSequenceKey: string | null = null
+
   $effect(() => {
     if (typeof document === 'undefined') {
       return
     }
 
     const resolvedSequence = resolveMaybeGetter(sequence)
+    const resolvedOptions = resolveMaybeGetter(options)
+    const mergedOptions = {
+      ...getDefaultHotkeysOptions().hotkeySequence,
+      ...resolvedOptions,
+    } as CreateHotkeySequenceOptions
+
+    const { target: _t, ...optionsWithoutTarget } = mergedOptions
+
     if (resolvedSequence.length === 0) {
+      if (registration?.isActive) {
+        registration.unregister()
+        registration = null
+      }
+      lastSequenceKey = null
       return
     }
 
-    const registration = registerHotkeySequence(
+    const sequenceKey = formatHotkeySequence(resolvedSequence)
+
+    if (registration?.isActive && lastSequenceKey === sequenceKey) {
+      registration.callback = callback
+      registration.setOptions(optionsWithoutTarget)
+      return
+    }
+
+    if (registration?.isActive) {
+      registration.unregister()
+      registration = null
+    }
+
+    registration = registerHotkeySequence(
       document,
       resolvedSequence,
       callback,
-      options,
+      mergedOptions,
     )
+    lastSequenceKey = sequenceKey
+  })
 
-    return () => {
+  onDestroy(() => {
+    if (registration?.isActive) {
       registration.unregister()
+      registration = null
     }
   })
 }
@@ -126,26 +154,48 @@ export function createHotkeySequenceAttachment(
   options: MaybeGetter<CreateHotkeySequenceOptions> = {},
 ): Attachment<HTMLElement> {
   return (element) => {
-    let registration: ReturnType<typeof registerHotkeySequence> | null = null
+    let registration: SequenceRegistrationHandle | null = null
+    let lastSequenceKey: string | null = null
 
     $effect(() => {
       const resolvedSequence = resolveMaybeGetter(sequence)
+      const resolvedOptions = resolveMaybeGetter(options)
+      const mergedOptions = {
+        ...getDefaultHotkeysOptions().hotkeySequence,
+        ...resolvedOptions,
+      } as CreateHotkeySequenceOptions
 
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
+      const { target: _t, ...optionsWithoutTarget } = mergedOptions
 
       if (resolvedSequence.length === 0) {
+        if (registration?.isActive) {
+          registration.unregister()
+          registration = null
+        }
+        lastSequenceKey = null
         return
       }
 
+      const sequenceKey = formatHotkeySequence(resolvedSequence)
+
+      if (registration?.isActive && lastSequenceKey === sequenceKey) {
+        registration.callback = callback
+        registration.setOptions(optionsWithoutTarget)
+        return
+      }
+
+      if (registration?.isActive) {
+        registration.unregister()
+        registration = null
+      }
+
       registration = registerHotkeySequence(
         element,
         resolvedSequence,
         callback,
-        options,
+        mergedOptions,
       )
+      lastSequenceKey = sequenceKey
     })
 
     return () => {

package/src/createHotkeySequences.svelte.ts

@@ -0,0 +1,274 @@
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
+import { onDestroy } from 'svelte'
+import { SvelteMap, SvelteSet } from 'svelte/reactivity'
+import { getDefaultHotkeysOptions } from './HotkeysCtx'
+import { resolveMaybeGetter } from './internal.svelte'
+import type {
+  HotkeyCallback,
+  HotkeySequence,
+  SequenceRegistrationHandle,
+} from '@tanstack/hotkeys'
+import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte'
+import type { MaybeGetter } from './internal.svelte'
+import type { Attachment } from 'svelte/attachments'
+
+/**
+ * A single sequence definition for use with `createHotkeySequences`.
+ */
+export interface CreateHotkeySequenceDefinition {
+  /** Array of hotkey strings that form the sequence */
+  sequence: MaybeGetter<HotkeySequence>
+  /** The function to call when the sequence is completed */
+  callback: HotkeyCallback
+  /** Per-sequence options (merged on top of commonOptions) */
+  options?: MaybeGetter<CreateHotkeySequenceOptions>
+}
+
+type RegistrationRecord = {
+  handle: SequenceRegistrationHandle
+  target: Document | HTMLElement | Window
+}
+
+function cleanupRegistrations(
+  registrations:
+    | Map<string, RegistrationRecord>
+    | SvelteMap<string, RegistrationRecord>,
+) {
+  for (const { handle } of registrations.values()) {
+    if (handle.isActive) {
+      handle.unregister()
+    }
+  }
+  registrations.clear()
+}
+
+/**
+ * Register multiple global keyboard shortcut sequences for the current component.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createHotkeySequences } from '@tanstack/svelte-hotkeys'
+ *
+ *   createHotkeySequences([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *   ])
+ * </script>
+ * ```
+ */
+export function createHotkeySequences(
+  definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>,
+  commonOptions: MaybeGetter<CreateHotkeySequenceOptions> = {},
+): void {
+  const registrations = new SvelteMap<string, RegistrationRecord>()
+
+  onDestroy(() => {
+    cleanupRegistrations(registrations)
+  })
+
+  $effect(() => {
+    if (typeof document === 'undefined') {
+      return
+    }
+
+    const resolvedDefinitions = resolveMaybeGetter(definitions)
+    const resolvedCommonOptions = resolveMaybeGetter(commonOptions)
+    const nextKeys = new SvelteSet<string>()
+    const prepared: Array<{
+      registrationKey: string
+      def: CreateHotkeySequenceDefinition
+      mergedOptions: CreateHotkeySequenceOptions
+      sequenceString: string
+      resolvedSequence: HotkeySequence
+      resolvedTarget: Document | HTMLElement | Window
+    }> = []
+
+    for (let i = 0; i < resolvedDefinitions.length; i++) {
+      const def = resolvedDefinitions[i]!
+      const resolvedSequence = resolveMaybeGetter(def.sequence)
+      if (resolvedSequence.length === 0) {
+        continue
+      }
+
+      const resolvedDefOptions = def.options
+        ? resolveMaybeGetter(def.options)
+        : {}
+
+      const mergedOptions = {
+        ...getDefaultHotkeysOptions().hotkeySequence,
+        ...resolvedCommonOptions,
+        ...resolvedDefOptions,
+      } as CreateHotkeySequenceOptions
+
+      const resolvedTarget =
+        mergedOptions.target ??
+        (typeof document !== 'undefined' ? document : null)
+
+      if (!resolvedTarget) {
+        continue
+      }
+
+      const sequenceString = formatHotkeySequence(resolvedSequence)
+      const registrationKey = `${i}:${sequenceString}`
+      nextKeys.add(registrationKey)
+      prepared.push({
+        registrationKey,
+        def,
+        mergedOptions,
+        sequenceString,
+        resolvedSequence,
+        resolvedTarget,
+      })
+    }
+
+    for (const [key, record] of [...registrations.entries()]) {
+      if (!nextKeys.has(key)) {
+        if (record.handle.isActive) {
+          record.handle.unregister()
+        }
+        registrations.delete(key)
+      }
+    }
+
+    for (const p of prepared) {
+      const existing = registrations.get(p.registrationKey)
+      const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
+
+      if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
+        existing.handle.callback = p.def.callback
+        existing.handle.setOptions(optionsWithoutTarget)
+        continue
+      }
+
+      if (existing?.handle.isActive) {
+        existing.handle.unregister()
+      }
+      if (existing) {
+        registrations.delete(p.registrationKey)
+      }
+
+      const handle = getSequenceManager().register(
+        p.resolvedSequence,
+        p.def.callback,
+        {
+          ...optionsWithoutTarget,
+          target: p.resolvedTarget,
+        },
+      )
+      registrations.set(p.registrationKey, {
+        handle,
+        target: p.resolvedTarget,
+      })
+    }
+  })
+}
+
+/**
+ * Create an attachment for element-scoped multi-sequence registration.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createHotkeySequencesAttachment } from '@tanstack/svelte-hotkeys'
+ *
+ *   const vim = createHotkeySequencesAttachment([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *   ])
+ * </script>
+ *
+ * <div tabindex="0" {@attach vim}>Editor</div>
+ * ```
+ */
+export function createHotkeySequencesAttachment(
+  definitions: MaybeGetter<Array<CreateHotkeySequenceDefinition>>,
+  commonOptions: MaybeGetter<CreateHotkeySequenceOptions> = {},
+): Attachment<HTMLElement> {
+  return (element) => {
+    const registrations = new SvelteMap<string, RegistrationRecord>()
+
+    $effect(() => {
+      const resolvedDefinitions = resolveMaybeGetter(definitions)
+      const resolvedCommonOptions = resolveMaybeGetter(commonOptions)
+      const nextKeys = new SvelteSet<string>()
+      const prepared: Array<{
+        registrationKey: string
+        def: CreateHotkeySequenceDefinition
+        mergedOptions: CreateHotkeySequenceOptions
+        sequenceString: string
+        resolvedSequence: HotkeySequence
+      }> = []
+
+      for (let i = 0; i < resolvedDefinitions.length; i++) {
+        const def = resolvedDefinitions[i]!
+        const resolvedSequence = resolveMaybeGetter(def.sequence)
+        if (resolvedSequence.length === 0) {
+          continue
+        }
+
+        const resolvedDefOptions = def.options
+          ? resolveMaybeGetter(def.options)
+          : {}
+
+        const mergedOptions = {
+          ...getDefaultHotkeysOptions().hotkeySequence,
+          ...resolvedCommonOptions,
+          ...resolvedDefOptions,
+        } as CreateHotkeySequenceOptions
+
+        const sequenceString = formatHotkeySequence(resolvedSequence)
+        const registrationKey = `${i}:${sequenceString}`
+        nextKeys.add(registrationKey)
+        prepared.push({
+          registrationKey,
+          def,
+          mergedOptions,
+          sequenceString,
+          resolvedSequence,
+        })
+      }
+
+      for (const [key, record] of [...registrations.entries()]) {
+        if (!nextKeys.has(key)) {
+          if (record.handle.isActive) {
+            record.handle.unregister()
+          }
+          registrations.delete(key)
+        }
+      }
+
+      for (const p of prepared) {
+        const existing = registrations.get(p.registrationKey)
+        const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
+
+        if (existing?.handle.isActive && existing.target === element) {
+          existing.handle.callback = p.def.callback
+          existing.handle.setOptions(optionsWithoutTarget)
+          continue
+        }
+
+        if (existing?.handle.isActive) {
+          existing.handle.unregister()
+        }
+        if (existing) {
+          registrations.delete(p.registrationKey)
+        }
+
+        const handle = getSequenceManager().register(
+          p.resolvedSequence,
+          p.def.callback,
+          {
+            ...optionsWithoutTarget,
+            target: element,
+          },
+        )
+        registrations.set(p.registrationKey, { handle, target: element })
+      }
+    })
+
+    return () => {
+      cleanupRegistrations(registrations)
+    }
+  }
+}

package/src/createHotkeys.svelte.ts

@@ -1,8 +1,7 @@
 import {
   detectPlatform,
-  formatHotkey,
   getHotkeyManager,
-  rawHotkeyToParsedHotkey,
+  normalizeRegisterableHotkey,
 } from '@tanstack/hotkeys'
 import { onDestroy } from 'svelte'
 import { SvelteMap, SvelteSet } from 'svelte/reactivity'
@@ -30,16 +29,6 @@ export interface CreateHotkeyDefinition {
   options?: MaybeGetter<CreateHotkeyOptions>
 }
 
-function normalizeHotkey(
-  hotkey: RegisterableHotkey,
-  options: CreateHotkeyOptions,
-): Hotkey {
-  const platform = options.platform ?? detectPlatform()
-  return typeof hotkey === 'string'
-    ? hotkey
-    : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)
-}
-
 type RegistrationRecord = {
   handle: HotkeyRegistrationHandle
   target: Document | HTMLElement | Window
@@ -121,7 +110,10 @@ export function createHotkeys(
         continue
       }
 
-      const hotkeyString = normalizeHotkey(resolvedHotkey, mergedOptions)
+      const hotkeyString = normalizeRegisterableHotkey(
+        resolvedHotkey,
+        mergedOptions.platform ?? detectPlatform(),
+      )
       const registrationKey = `${i}:${hotkeyString}`
       nextKeys.add(registrationKey)
       prepared.push({
@@ -225,7 +217,10 @@ export function createHotkeysAttachment(
           ...resolvedDefOptions,
         } as CreateHotkeyOptions
 
-        const hotkeyString = normalizeHotkey(resolvedHotkey, mergedOptions)
+        const hotkeyString = normalizeRegisterableHotkey(
+          resolvedHotkey,
+          mergedOptions.platform ?? detectPlatform(),
+        )
         const registrationKey = `${i}:${hotkeyString}`
         nextKeys.add(registrationKey)
         prepared.push({

package/src/index.ts

@@ -4,6 +4,7 @@ export * from '@tanstack/hotkeys'
 export * from './createHotkey.svelte'
 export * from './createHotkeys.svelte'
 export * from './createHotkeySequence.svelte'
+export * from './createHotkeySequences.svelte'
 export * from './createHotkeyRecorder.svelte'
 export * from './createHotkeySequenceRecorder.svelte'
 export * from './getHeldKeys.svelte'