Feat svelte adapter by kunaaal13 · Pull Request #45 · TanStack/hotkeys

kunaaal13 · 2026-02-25T09:29:37Z

🎯 Changes

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

… adding target option

kunaaal13 · 2026-02-26T17:45:00Z

@KevinVandy have added examples as well. What is the process now.

KevinVandy · 2026-02-26T17:51:43Z

I just have to have enough time to review

kunaaal13 · 2026-03-08T19:06:38Z

@KevinVandy how does it look? can i help with something?

KevinVandy · 2026-03-08T19:41:06Z

I'm doing a deeper review and testing now. First pass was just getting all the tests to pass

pkg-pr-new · 2026-03-08T19:42:06Z

Open in StackBlitz

@tanstack/angular-hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/angular-hotkeys@45

@tanstack/hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/hotkeys@45

@tanstack/hotkeys-devtools

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/hotkeys-devtools@45

@tanstack/preact-hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/preact-hotkeys@45

@tanstack/preact-hotkeys-devtools

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/preact-hotkeys-devtools@45

@tanstack/react-hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/react-hotkeys@45

@tanstack/react-hotkeys-devtools

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/react-hotkeys-devtools@45

@tanstack/solid-hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/solid-hotkeys@45

@tanstack/solid-hotkeys-devtools

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/solid-hotkeys-devtools@45

@tanstack/svelte-hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/svelte-hotkeys@45

@tanstack/vue-hotkeys

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/vue-hotkeys@45

@tanstack/vue-hotkeys-devtools

npm i https://pkg.pr.new/TanStack/hotkeys/@tanstack/vue-hotkeys-devtools@45

commit: e153132

paoloricciuti

Took a look at the code part and there are a few confusing things...if the code is working either there's probably some edge case missing or the code can be simplified a lot while continuing to work.

If you need any help feel free to ping me!

paoloricciuti · 2026-03-09T17:36:39Z

packages/svelte-hotkeys/src/createHotkey.svelte.ts

+ *   let ref = $state<HTMLDivElement | null>(null)
+ *   let count = $state(0)
+ *
+ *   createHotkey('Mod+S', () => {
+ *     console.log('Mod+S pressed')
+ *     count++
+ *   }, { target: ref })
+ * </script>
+ *
+ * <div bind:this={ref}>
+ *   Count: {count}
+ * </div>


Rather than doing this I would create an attachment (docs: https://svelte.dev/docs/svelte/@attach) that can retrieve a reference automatically from the template without using an extra variable.

Probably best as its own function since global hotkeys are a common use case.

const increment = createHotkeyAttachment('Mod+S', () => { console.log('Mod+S pressed') count++ });

<div {@attach increment}> Count: {count} </div>

Or maybe: Always return an attachment/an object that can create an attachment and make it possible to disable the global nature of the hotkey. I.e.

const increment = createHotkey('Mod+S', () => { console.log('Mod+S pressed') count++ }, { target: null });

paoloricciuti · 2026-03-09T17:38:13Z

packages/svelte-hotkeys/src/createHotkey.svelte.ts

+  let callbackRef = callback
+  let managerRef = manager
+
+  $effect(() => {
+    callbackRef = callback
+    managerRef = manager
+  })


This feels weird to me: callback and manager are not stateful variables so this $effect will never re-trigger no?

paoloricciuti · 2026-03-09T17:39:48Z

packages/svelte-hotkeys/src/createHotkey.svelte.ts

+        ? document
+        : null
+
+    // Skip if no valid target (SSR or ref still null)


$effect doesn't run during SSR so if you were architecting around SSR maybe something can be simplified?

paoloricciuti · 2026-03-09T17:41:07Z

packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts

+ * </script>
+ *
+ * <div>
+ *   <button on:click={recorder.startRecording}>


Suggested change

* <button on:click={recorder.startRecording}>

* <button onclick={recorder.startRecording}>

paoloricciuti · 2026-03-09T17:41:46Z

packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts

+ *   {recorder.recordedHotkey && (
+ *     <div>Recording: {recorder.recordedHotkey}</div>
+ *   )}


Suggested change

* {recorder.recordedHotkey && (

* <div>Recording: {recorder.recordedHotkey}</div>

* )}

* {#if recorder.recordedHotkey}

* <div>Recording: {recorder.recordedHotkey}</div>

* {/if}

paoloricciuti · 2026-03-09T17:44:43Z

packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts

+  const mergedOptions = {
+    ...getDefaultHotkeysOptions().hotkeyRecorder,
+    ...options,
+  } as HotkeyRecorderOptions
+
+  const recorder = new HotkeyRecorder(mergedOptions)
+
+  // Sync options on every render (same pattern as createHotkey)
+  // This ensures callbacks always have access to latest values
+  $effect(() => {
+    recorder.setOptions(mergedOptions)
+  })


mergedOptions is not a stateful variable so this effect will always run once...we should probably make mergedOptions a derived (but then you should pay attention because accepting an object as argument instead of a getter means the user will not be able to reassign the whole options reactively but just mutate them)...I would probably switch every option to be a a getter.

If the options were not spread, the individual properties could already be made reactive via get prop() { return ... } at the call site.

For APIs like this it can also be convenient to have the function take either a callback returning an options object or an options object directly. That way you do not necessarily need many smaller functions or get properties to have something reactive.

Forcing each property to be a callback makes the calling code a bit noisy, but you could also potentially accept T | (() => T) on each, depending on how much overloading one is comfortable with, though this will clash on properties that are already callbacks...

paoloricciuti · 2026-03-09T17:45:38Z

packages/svelte-hotkeys/src/createHotkeySequence.svelte.ts

+  // Refs to capture current values for use in effect without adding dependencies
+  let callbackRef = callback
+  let optionsRef = mergedOptions
+
+  $effect(() => {
+    callbackRef = callback
+    optionsRef = mergedOptions
+  })


Same as above

brunnerh · 2026-03-09T20:36:30Z

docs/framework/svelte/guides/key-state-tracking.md

Bit of syntax chaos here.

Old store syntax on $heldKeys.

What looks like broken reactivity on isShiftHeld (neither .current, nor $)

class:active={...} could be replaced with the newer clsx object syntax: class={{ active: ... }}

brunnerh · 2026-03-09T20:42:06Z

packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts

+  const mergedOptions = {
+    ...getDefaultHotkeysOptions().hotkeyRecorder,
+    ...options,
+  } as HotkeyRecorderOptions
+
+  const recorder = new HotkeyRecorder(mergedOptions)
+
+  // Sync options on every render (same pattern as createHotkey)
+  // This ensures callbacks always have access to latest values
+  $effect(() => {
+    recorder.setOptions(mergedOptions)
+  })


If the options were not spread, the individual properties could already be made reactive via get prop() { return ... } at the call site.

For APIs like this it can also be convenient to have the function take either a callback returning an options object or an options object directly. That way you do not necessarily need many smaller functions or get properties to have something reactive.

Forcing each property to be a callback makes the calling code a bit noisy, but you could also potentially accept T | (() => T) on each, depending on how much overloading one is comfortable with, though this will clash on properties that are already callbacks...

brunnerh · 2026-03-09T20:53:56Z

docs/framework/svelte/guides/hotkeys.md

+  import { HotkeysProvider } from '@tanstack/svelte-hotkeys'
+</script>
+
+<HotkeysProvider


I would promote the use of setHotkeysContext over this. The component is essentially pointless unless you have multiple providers for different parts of the application at the same time.

Just call the function in the script, save one level of nesting.

kunaaal13 · 2026-03-10T12:57:01Z

@KevinVandy i am up for the changes, will push the fixes as per discussion above in some hours?

KevinVandy · 2026-03-10T13:19:05Z

@kunaaal13 Heads up that I'm pushing a major refactor here in a little bit too.

KevinVandy · 2026-03-10T16:20:37Z

@paoloricciuti @brunnerh I did a big refactor based on your feedback. I think the attachment stuff works a lot better, but had to keep a separate createHotkeyAttachment function to simplify the default document/window one.

Also, I just competely got rid of @tanstack/svelte-store for now since the simple state getter wrappers seem to work better. I might bring back tanstack store in more correct way later.

kunaaal13 added 2 commits February 25, 2026 13:55

initial setup

1512354

feat: Update dependencies and export components in svelte-hotkeys

fbd6b6a

kunaaal13 marked this pull request as draft February 25, 2026 09:29

kunaaal13 added 5 commits February 25, 2026 15:06

added jsdoc examples

8a02594

setup example 1

0e75e7f

feat: Enhance Svelte hotkeys functionality and update examples

1f2bb4e

refactor: Improve hotkey sequence implementation in Svelte example by…

22d5bbe

… adding target option

add more examples for svelte

86cb965

Merge branch 'main' into feat-svelte-adapter

7316bef

KevinVandy marked this pull request as ready for review March 8, 2026 18:30

fix a bunch of stuff and generate docs

b557270

autofix-ci bot and others added 4 commits March 8, 2026 19:42

ci: apply automated fixes

73c276c

fix provider errors in examples

04ab182

get examples to actually work

3509cb7

ci: apply automated fixes

5ac287a

paoloricciuti reviewed Mar 9, 2026

View reviewed changes

brunnerh reviewed Mar 9, 2026

View reviewed changes

Merge branch 'main' into feat-svelte-adapter

251f71f

KevinVandy added 2 commits March 10, 2026 09:17

refactor svelte adapter

80f8a4e

update docs and fix type error

0a637f3

KevinVandy added 2 commits March 10, 2026 14:50

update svelte hotkeys version

df2b4ba

update example versions

402f322

KevinVandy merged commit 75ce7c8 into TanStack:main Mar 10, 2026

	* <button on:click={recorder.startRecording}>
	* <button onclick={recorder.startRecording}>

Uh oh!

Conversation

kunaaal13 commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Uh oh!

kunaaal13 commented Feb 26, 2026

Uh oh!

KevinVandy commented Feb 26, 2026

Uh oh!

kunaaal13 commented Mar 8, 2026

Uh oh!

KevinVandy commented Mar 8, 2026

Uh oh!

pkg-pr-new bot commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paoloricciuti left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kunaaal13 commented Mar 10, 2026

Uh oh!

KevinVandy commented Mar 10, 2026

Uh oh!

KevinVandy commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kunaaal13 commented Feb 25, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 8, 2026 •

edited

Loading