+ {{onHotkey "Escape" @onClosePanel target=this.panelEl}}
+ Panel content
+
+
+}
+```
+
+### `preventDefault`
+
+Prevent the browser default action (e.g., browser save dialog for `Mod+S`). This is `true` by default.
+
+```gts
+{{onHotkey "Mod+S" @onSave preventDefault=true}}
+```
+
+### `stopPropagation`
+
+Stop the event from propagating to parent elements:
+
+```gts
+{{onHotkey "Escape" @onClose stopPropagation=true}}
+```
+
+### `eventType`
+
+Listen for `keyup` events instead of the default `keydown`:
+
+```gts
+{{onHotkey "Escape" @onClose eventType="keyup"}}
+```
+
+### `requireReset`
+
+When `true`, the hotkey fires at most once per key-hold. The user must release the key and press again to fire the callback a second time.
+
+```gts
+{{onHotkey "Escape" @onClose requireReset=true}}
+```
+
+### `ignoreInputs`
+
+By default, hotkeys are suppressed when an input element is focused. Set `ignoreInputs` to `false` to fire the callback even when an input, textarea, or contenteditable element has focus:
+
+```gts
+{{onHotkey "Enter" @onSubmit ignoreInputs=false}}
+```
+
+### `conflictBehavior`
+
+Control what happens when the same hotkey is registered twice:
+
+```gts
+{{onHotkey "Mod+S" @onSave conflictBehavior="replace"}}
+```
+
+### `platform`
+
+Force a specific platform for `Mod` resolution:
+
+```gts
+{{onHotkey "Mod+S" @onSave platform="mac"}}
+```
+
+## Metadata (name & description)
+
+Every hotkey registration can carry a `meta` object with a `name` and `description`. This metadata is informational only -- it does not affect hotkey behavior -- but it flows through to registrations and devtools, making it easy to build shortcut palettes and help screens.
+
+```gts
+{{onHotkey "Mod+S" @onSave meta=(hash name="Save" description="Save the document")}}
+```
+
+## Automatic Cleanup
+
+Registrations are cleaned up automatically when the helper is destroyed -- for example, when the component is removed from the DOM or when an `{{#if}}` block becomes falsy.
+
+## The Hotkey Manager
+
+You can access the underlying manager directly when needed:
+
+```ts
+import { getHotkeyManager } from '@tanstack/ember-hotkeys';
+
+const manager = getHotkeyManager();
+manager.isRegistered('Mod+S');
+manager.getRegistrationCount();
+```
diff --git a/docs/framework/ember/guides/key-state-tracking.md b/docs/framework/ember/guides/key-state-tracking.md
new file mode 100644
index 00000000..4253d062
--- /dev/null
+++ b/docs/framework/ember/guides/key-state-tracking.md
@@ -0,0 +1,106 @@
+---
+title: Key State Tracking Guide
+id: key-state-tracking
+---
+
+TanStack Hotkeys provides `KeyStateTracker` for tracking live keyboard state. The tracker is a singleton re-exported from `@tanstack/ember-hotkeys` that automatically manages `keydown`/`keyup`/`blur` listeners and exposes reactive state via a TanStack Store.
+
+## `KeyStateTracker`
+
+```ts
+import { getKeyStateTracker } from '@tanstack/ember-hotkeys';
+
+const tracker = getKeyStateTracker();
+
+tracker.getHeldKeys(); // ['Control', 'Shift']
+tracker.isKeyHeld('Shift'); // true
+```
+
+## Common Patterns
+
+### Hold-to-Reveal UI
+
+```gts
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { registerDestructor } from '@ember/destroyable';
+import { getKeyStateTracker } from '@tanstack/ember-hotkeys';
+
+export default class FileActions extends Component {
+ @tracked isShiftHeld = false;
+
+ constructor(owner: unknown, args: Record
+ {{#if this.heldKeys.length}}
+ Keys: {{this.heldKeys}}
+ {{else}}
+ No keys held
+ {{/if}}
+
+
+}
+```
+
+## Under the Hood
+
+The `KeyStateTracker` is a singleton that manages its own `keydown`, `keyup`, and `blur` listeners. It uses a TanStack Store for reactive state, so you can subscribe to changes and read current state:
+
+```ts
+import { getKeyStateTracker } from '@tanstack/ember-hotkeys';
+
+const tracker = getKeyStateTracker();
+
+// Read current state
+tracker.store.state.heldKeys; // ['Control', 'A']
+tracker.store.state.heldCodes; // { Control: 'ControlLeft', A: 'KeyA' }
+
+// Subscribe to changes
+const unsubscribe = tracker.store.subscribe(() => {
+ console.log('Currently held:', tracker.getHeldKeys());
+});
+```
diff --git a/docs/framework/ember/guides/sequence-recording.md b/docs/framework/ember/guides/sequence-recording.md
new file mode 100644
index 00000000..9e65ee87
--- /dev/null
+++ b/docs/framework/ember/guides/sequence-recording.md
@@ -0,0 +1,19 @@
+---
+title: Sequence Recording Guide
+id: sequence-recording
+---
+
+Use `HotkeySequenceRecorder` from `@tanstack/ember-hotkeys` for recording multi-key sequences. It exposes `start`, `stop`, `cancel`, and `commit` methods, along with state like `isRecording`, `steps`, and `recordedSequence`.
+
+```ts
+import { HotkeySequenceRecorder } from '@tanstack/ember-hotkeys';
+
+const recorder = new HotkeySequenceRecorder({
+ onRecord: (sequence) => console.log('Recorded:', sequence),
+ onCancel: () => console.log('Cancelled'),
+});
+```
+
+## `ignoreInputs`
+
+The `HotkeySequenceRecorder` supports an `ignoreInputs` option (defaults to `true`). When `true`, the recorder will not intercept normal typing in text inputs, textareas, selects, or contentEditable elements — keystrokes pass through to the input as usual. Pressing **Escape** still cancels recording even when focused on an input. Set `ignoreInputs: false` if you want the recorder to capture keys from within input elements.
diff --git a/docs/framework/ember/guides/sequences.md b/docs/framework/ember/guides/sequences.md
new file mode 100644
index 00000000..222cb780
--- /dev/null
+++ b/docs/framework/ember/guides/sequences.md
@@ -0,0 +1,105 @@
+---
+title: Sequences Guide
+id: sequences
+---
+
+TanStack Hotkeys supports multi-key sequences in Ember, where keys are pressed one after another rather than simultaneously.
+
+## Basic Usage
+
+```gts
+import onHotkeySequence from '@tanstack/ember-hotkeys/helpers/on-hotkey-sequence';
+import { array } from '@ember/helper';
+
+const scrollToTop = () => {
+ window.scrollTo({ top: 0, behavior: 'smooth' });
+};
+
+
+ {{onHotkeySequence (array "G" "G") scrollToTop}}
+
+```
+
+## Sequence Options
+
+Options are passed as named arguments, just like `{{onHotkey}}`:
+
+```gts
+{{onHotkeySequence (array "G" "G") @onScrollToTop timeout=1000 enabled=true}}
+```
+
+### `timeout`
+
+The maximum time (in milliseconds) between key presses in a sequence. Defaults to 1000ms.
+
+```gts
+{{onHotkeySequence (array "D" "I" "W") @onDeleteWord timeout=500}}
+```
+
+### Reactive `enabled`
+
+When disabled, the sequence **stays registered** (visible in devtools); only execution is suppressed.
+
+```gts
+{{onHotkeySequence (array "G" "G") @onScrollToTop enabled=@isVimMode}}
+```
+
+### `meta`
+
+Sequences support the same `meta` option as hotkeys, allowing you to attach a `name` and `description` for use in shortcut palettes and devtools.
+
+```gts
+{{onHotkeySequence (array "G" "G") @onScrollToTop
+ meta=(hash name="Go to Top" description="Scroll to the top of the page")
+}}
+```
+
+See the [Hotkeys Guide](./hotkeys#metadata-name--description) for more details on metadata.
+
+## Chained Modifier Chords
+
+You can use modifiers within sequence steps:
+
+```gts
+{{onHotkeySequence (array "Shift+R" "Shift+T") @onAction}}
+```
+
+While a sequence is in progress, **modifier-only** keydown events (Shift, Control, Alt, or Meta pressed alone) are ignored: they do not advance the sequence and do not reset progress.
+
+## Common Patterns
+
+### Vim-Style Navigation
+
+```gts
+import onHotkeySequence from '@tanstack/ember-hotkeys/helpers/on-hotkey-sequence';
+import { array } from '@ember/helper';
+
+
+ {{onHotkeySequence (array "G" "G") @onScrollToTop}}
+ {{onHotkeySequence (array "G" "Shift+G") @onScrollToBottom}}
+ {{onHotkeySequence (array "D" "D") @onDeleteLine}}
+ {{onHotkeySequence (array "D" "W") @onDeleteWord}}
+ {{onHotkeySequence (array "C" "I" "W") @onChangeInnerWord}}
+
+```
+
+### Konami Code
+
+```gts
+{{onHotkeySequence
+ (array "ArrowUp" "ArrowUp" "ArrowDown" "ArrowDown" "B" "A")
+ @onEasterEgg
+ timeout=2000
+}}
+```
+
+## Under the Hood
+
+`{{onHotkeySequence}}` uses the singleton `SequenceManager`. You can also access it directly:
+
+```ts
+import { createSequenceMatcher, getSequenceManager } from '@tanstack/ember-hotkeys';
+
+const manager = getSequenceManager();
+const matcher = createSequenceMatcher(['G', 'G'], { timeout: 1000 });
+```
diff --git a/docs/framework/ember/quick-start.md b/docs/framework/ember/quick-start.md
new file mode 100644
index 00000000..d062691d
--- /dev/null
+++ b/docs/framework/ember/quick-start.md
@@ -0,0 +1,112 @@
+---
+title: Quick Start
+id: quick-start
+---
+
+## Installation
+
+Don't have TanStack Hotkeys installed yet? See the [Installation](../../installation) page for instructions.
+
+## Your First Hotkey
+
+The `{{onHotkey}}` helper is the primary way to register keyboard shortcuts in Ember:
+
+```gts
+import onHotkey from '@tanstack/ember-hotkeys/helpers/on-hotkey';
+
+const save = () => {
+ saveDocument();
+};
+
+
+ {{onHotkey "Mod+S" save}}
+ Press Cmd+S (Mac) or Ctrl+S (Windows) to save
+
+```
+
+The `Mod` modifier automatically resolves to `Meta` (Command) on macOS and `Control` on Windows/Linux, so your shortcuts work across platforms without extra logic.
+
+## Common Patterns
+
+### Multiple Hotkeys
+
+```gts
+import onHotkey from '@tanstack/ember-hotkeys/helpers/on-hotkey';
+
+
+ {{onHotkey "Mod+S" @onSave}}
+ {{onHotkey "Mod+Z" @onUndo}}
+ {{onHotkey "Mod+Shift+Z" @onRedo}}
+ {{onHotkey "Mod+F" @onSearch}}
+ {{onHotkey "Escape" @onDismiss}}
+
+```
+
+### Conditional Hotkeys
+
+Enable or disable hotkeys based on application state via the `enabled` option:
+
+```gts
+import onHotkey from '@tanstack/ember-hotkeys/helpers/on-hotkey';
+
+
+ {{onHotkey "Escape" @onClose enabled=@isOpen}}
+
+```
+
+### Multi-Key Sequences
+
+Register Vim-style key sequences with the `{{onHotkeySequence}}` helper:
+
+```gts
+import onHotkeySequence from '@tanstack/ember-hotkeys/helpers/on-hotkey-sequence';
+import { array } from '@ember/helper';
+
+
+ {{onHotkeySequence (array "G" "G") @onScrollToTop}}
+ {{onHotkeySequence (array "G" "Shift+G") @onScrollToBottom}}
+
+```
+
+### Displaying Hotkeys in the UI
+
+Format hotkeys for platform-aware display:
+
+```gts
+import { formatForDisplay } from '@tanstack/ember-hotkeys';
+import onHotkey from '@tanstack/ember-hotkeys/helpers/on-hotkey';
+
+
+ {{onHotkey "Mod+S" @onSave}}
+
+
+```
+
+## Test Helpers
+
+The package ships with test utilities for writing integration tests:
+
+```ts
+import { triggerKeyPress, triggerKeyRelease } from '@tanstack/ember-hotkeys/test-support';
+
+test('it saves on Mod+S', async function (assert) {
+ assert.expect(1);
+
+ const onSave = () => assert.ok(true, 'save was called');
+
+ await render(
+
+ {{onHotkey "Mod+S" onSave}}
+ ,
+ );
+
+ await triggerKeyPress('Mod+S');
+});
+```
+
+## Next Steps
+
+- [Hotkeys Guide](./guides/hotkeys)
+- [Sequences Guide](./guides/sequences)
diff --git a/docs/framework/ember/reference/index.md b/docs/framework/ember/reference/index.md
new file mode 100644
index 00000000..b6ac793a
--- /dev/null
+++ b/docs/framework/ember/reference/index.md
@@ -0,0 +1,41 @@
+---
+id: "@tanstack/ember-hotkeys"
+title: "@tanstack/ember-hotkeys"
+---
+
+# @tanstack/ember-hotkeys
+
+## Helpers
+
+- [onHotkey](../guides/hotkeys) — Register a single keyboard shortcut
+- [onHotkeySequence](../guides/sequences) — Register a multi-key sequence (Vim-style)
+
+## Test Support
+
+- `triggerKeyPress(combo)` — Dispatch a `keydown` event for the given hotkey combo and settle
+- `triggerKeyRelease(combo)` — Dispatch a `keyup` event for the given hotkey combo and settle
+
+Import from `@tanstack/ember-hotkeys/test-support`.
+
+## Interfaces
+
+- `OnHotkeySignature` — Glint signature for the `onHotkey` helper
+- `OnHotkeyOptions` — Named arguments accepted by `onHotkey`
+- `OnHotkeySequenceSignature` — Glint signature for the `onHotkeySequence` helper
+- `OnHotkeySequenceOptions` — Named arguments accepted by `onHotkeySequence`
+
+## Template Registry
+
+Import `Registry` from `@tanstack/ember-hotkeys/template-registry` and merge it into your app's registry for Glint strict-mode type checking:
+
+```ts
+import type { Registry as EmberHotkeysRegistry } from '@tanstack/ember-hotkeys/template-registry';
+
+declare module '@glint/environment-ember-loose/registry' {
+ export default interface Registry extends EmberHotkeysRegistry {}
+}
+```
+
+## Re-exports
+
+This package re-exports everything from the core [`@tanstack/hotkeys`](../../../reference/index) package, so there is no need to install the core package separately.
diff --git a/docs/installation.md b/docs/installation.md
index f92e3995..899e9f5d 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -8,6 +8,7 @@ TanStack Hotkeys is compatible with various front-end frameworks. Install the co
angular: @tanstack/angular-hotkeys
+ember: @tanstack/ember-hotkeys
lit: @tanstack/lit-hotkeys
preact: @tanstack/preact-hotkeys
react: @tanstack/react-hotkeys
@@ -84,6 +85,16 @@ Lit currently ships the hotkeys adapter only, so no dedicated Lit devtools packa
+
+
+### Ember
+
+Start with the [Quick Start](./framework/ember/quick-start) guide and the Ember-specific [guides](./framework/ember/guides/hotkeys).
+
+Ember currently ships the hotkeys adapter only, so no dedicated Ember devtools package is required.
+
+
+
preact: @tanstack/preact-devtools
diff --git a/docs/overview.md b/docs/overview.md
index 061d8b89..330d123c 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -10,7 +10,7 @@ TanStack Hotkeys is a **type-safe**, **framework-agnostic** library for handling
## Motivation
-On the surface, keyboard shortcuts are a simple concept, and you would think that it should just take a couple of lines of code to implement them. And sometimes, it can be that simple. However, there are enough small "gotchas" that can eventually add up to an annoying amount of complexity when you need to consider multiple keyboard layouts, operating systems, custom shortcuts, conflicting hotkey scopes, properly ignoring input elements, and more.
+On the surface, keyboard shortcuts are a simple concept, and you would think that it should just take a couple of lines of code to implement them. And sometimes, it can be that simple. However, there are enough small "gotchas" that can eventually add up to an annoying amount of complexity when you need to consider multiple keyboard layouts, operating systems, custom shortcuts, conflicting hotkey scopes, properly ignoring input elements, and more.
Surprisingly, in our experience, even AI often struggles to get hotkey management fully correct. We believe that providing a library that brings type-safety and well thought out cross-platform compatibility to hotkey management is a valuable contribution to the community.
@@ -46,9 +46,9 @@ Surprisingly, in our experience, even AI often struggles to get hotkey managemen
- Platform-aware formatting (e.g., `⌘⇧S` on Mac vs `Ctrl+Shift+S` on Windows) for cheatsheet UIs
- **Framework Adapters**
- - React and Preact hooks, Solid primitives, Angular inject APIs, Vue composables, and Lit controllers/decorators
+ - React and Preact hooks, Solid primitives, Angular inject APIs, Vue composables, Lit controllers/decorators, Svelte actions, and Ember helpers
- **Awesome Devtools!**
- See all currently registered hotkeys, held keys, and more in real-time.
-For a complete walkthrough, see the [React Quick Start](framework/react/quick-start), [Angular Quick Start](framework/angular/quick-start), [Vue Quick Start](framework/vue/quick-start) or [Lit Quick Start](framework/lit/quick-start).
+For a complete walkthrough, see the [React Quick Start](framework/react/quick-start), [Angular Quick Start](framework/angular/quick-start), [Vue Quick Start](framework/vue/quick-start), [Lit Quick Start](framework/lit/quick-start) or [Ember Quick Start](framework/ember/quick-start).
diff --git a/knip.json b/knip.json
index 51546bad..e88469f2 100644
--- a/knip.json
+++ b/knip.json
@@ -1,7 +1,7 @@
{
"$schema": "https://unpkg.com/knip@5/schema.json",
"ignoreDependencies": ["@faker-js/faker"],
- "ignoreWorkspaces": ["examples/**"],
+ "ignoreWorkspaces": ["examples/**", "packages/ember-hotkeys"],
"workspaces": {
"packages/react-hotkeys": {
"ignore": []
diff --git a/package.json b/package.json
index ac469b34..cacfcd7e 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
"clean": "find . -name 'dist' -type d -prune -exec rm -rf {} +",
"clean:node_modules": "find . -name 'node_modules' -type d -prune -exec rm -rf {} +",
"clean:all": "pnpm run clean && pnpm run clean:node_modules",
- "copy:readme": "cp README.md packages/hotkeys/README.md && cp README.md packages/hotkeys-devtools/README.md && cp README.md packages/angular-hotkeys/README.md && cp README.md packages/react-hotkeys/README.md && cp README.md packages/react-hotkeys-devtools/README.md && cp README.md packages/preact-hotkeys/README.md && cp README.md packages/preact-hotkeys-devtools/README.md && cp README.md packages/solid-hotkeys/README.md && cp README.md packages/solid-hotkeys-devtools/README.md && cp README.md packages/vue-hotkeys/README.md && cp README.md packages/vue-hotkeys-devtools/README.md && cp README.md packages/lit-hotkeys/README.md && cp README.md packages/svelte-hotkeys/README.md",
+ "copy:readme": "cp README.md packages/hotkeys/README.md && cp README.md packages/hotkeys-devtools/README.md && cp README.md packages/angular-hotkeys/README.md && cp README.md packages/react-hotkeys/README.md && cp README.md packages/react-hotkeys-devtools/README.md && cp README.md packages/preact-hotkeys/README.md && cp README.md packages/preact-hotkeys-devtools/README.md && cp README.md packages/solid-hotkeys/README.md && cp README.md packages/solid-hotkeys-devtools/README.md && cp README.md packages/vue-hotkeys/README.md && cp README.md packages/vue-hotkeys-devtools/README.md && cp README.md packages/lit-hotkeys/README.md && cp README.md packages/svelte-hotkeys/README.md && cp README.md packages/ember-hotkeys/README.md",
"dev": "pnpm run watch",
"format": "prettier --experimental-cli --ignore-unknown '**/*' --write",
"generate-docs": "node scripts/generate-docs.ts && pnpm run copy:readme",
@@ -83,6 +83,7 @@
},
"overrides": {
"@tanstack/angular-hotkeys": "workspace:*",
+ "@tanstack/ember-hotkeys": "workspace:*",
"@tanstack/hotkeys": "workspace:*",
"@tanstack/hotkeys-devtools": "workspace:*",
"@tanstack/lit-hotkeys": "workspace:*",
diff --git a/packages/ember-hotkeys/.env.development b/packages/ember-hotkeys/.env.development
new file mode 100644
index 00000000..8380c3a6
--- /dev/null
+++ b/packages/ember-hotkeys/.env.development
@@ -0,0 +1,8 @@
+# This file is committed to git and should not contain any secrets.
+#
+# Vite recommends using .env.local or .env.[mode].local if you need to manage secrets
+# SEE: https://vite.dev/guide/env-and-mode.html#env-files for more information.
+
+
+# Default NODE_ENV with vite build --mode=test is production
+NODE_ENV=development
diff --git a/packages/ember-hotkeys/.gitignore b/packages/ember-hotkeys/.gitignore
new file mode 100644
index 00000000..1d025719
--- /dev/null
+++ b/packages/ember-hotkeys/.gitignore
@@ -0,0 +1,21 @@
+# compiled output
+dist/
+dist-tests/
+declarations/
+
+# from scenarios
+tmp/
+config/optional-features.json
+ember-cli-build.cjs
+
+# npm/pnpm/yarn pack output
+*.tgz
+
+# deps & caches
+node_modules/
+.eslintcache
+.prettiercache
+
+# potentially containing secrets
+*.local
+
diff --git a/packages/ember-hotkeys/.template-lintrc.mjs b/packages/ember-hotkeys/.template-lintrc.mjs
new file mode 100644
index 00000000..8b6625cd
--- /dev/null
+++ b/packages/ember-hotkeys/.template-lintrc.mjs
@@ -0,0 +1,4 @@
+export default {
+ extends: 'recommended',
+ checkHbsTemplateLiterals: false,
+};
diff --git a/packages/ember-hotkeys/README.md b/packages/ember-hotkeys/README.md
new file mode 100644
index 00000000..cb919754
--- /dev/null
+++ b/packages/ember-hotkeys/README.md
@@ -0,0 +1,124 @@
+
+ 
+
+
+
++ + + + + +
+ 
+ 
+ 
+ 
+
+
+### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
+
+
+
+# TanStack Hotkeys
+
+> [!NOTE]
+> 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.
+
+- Type-safe bindings — template strings (`Mod+Shift+S`, `Escape`) or parsed objects for full control
+- Flexible options — `keydown`/`keyup`, `preventDefault`, `stopPropagation`, conditional enabled, `requireReset`
+- Cross-platform Mod — maps to Cmd on macOS and Ctrl on Windows/Linux
+- Batteries included — validation + matching, sequences (Vim-style), key-state tracking, recorder UI helpers, framework adapters, and devtools
+
+## Read the docs →
+
++ +> [!NOTE] +> You may know **TanStack Hotkeys** by our adapter names, too! +> +> - [**React Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/react/react-hotkeys) +> - [**Preact Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/preact/preact-hotkeys) +> - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference) +> - [**Angular Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/angular/reference) +> - [**Vue Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/vue/reference) +> - [**Lit Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/lit/reference) +> - [**Svelte Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference) +> - [**Ember Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/ember/reference) + +## Get Involved + +- We welcome issues and pull requests! +- Participate in [GitHub discussions](https://github.com/TanStack/hotkeys/discussions) +- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ) +- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions + +## Partners + +
+
+
+
+
+
+
+## Explore the TanStack Ecosystem
+
+- TanStack Config – Tooling for JS/TS packages
+- TanStack DB – Reactive sync client store
+- TanStack DevTools – Unified devtools panel
+- TanStack Form – Type‑safe form state
+- TanStack Hotkeys – Type‑safe keyboard shortcuts
+- TanStack Query – Async state & caching
+- TanStack Ranger – Range & slider primitives
+- TanStack Router – Type‑safe routing, caching & URL state
+- TanStack Start – Full‑stack SSR & streaming
+- TanStack Store – Reactive data store
+- TanStack Table – Headless datagrids
+- TanStack Virtual – Virtualized rendering
+
+… and more at TanStack.com »
diff --git a/packages/ember-hotkeys/addon-main.cjs b/packages/ember-hotkeys/addon-main.cjs
new file mode 100644
index 00000000..f868d6b9
--- /dev/null
+++ b/packages/ember-hotkeys/addon-main.cjs
@@ -0,0 +1,4 @@
+'use strict';
+
+const { addonV1Shim } = require('@embroider/addon-shim');
+module.exports = addonV1Shim(__dirname);
diff --git a/packages/ember-hotkeys/babel.config.cjs b/packages/ember-hotkeys/babel.config.cjs
new file mode 100644
index 00000000..fe72f41b
--- /dev/null
+++ b/packages/ember-hotkeys/babel.config.cjs
@@ -0,0 +1,50 @@
+/**
+ * This babel.config is not used for publishing.
+ * It's only for the local editing experience
+ * (and linting)
+ */
+const { buildMacros } = require('@embroider/macros/babel');
+
+const {
+ babelCompatSupport,
+ templateCompatSupport,
+} = require('@embroider/compat/babel');
+
+const macros = buildMacros();
+
+// For scenario testing
+const isCompat = Boolean(process.env.ENABLE_COMPAT_BUILD);
+
+module.exports = {
+ plugins: [
+ [
+ '@babel/plugin-transform-typescript',
+ {
+ allExtensions: true,
+ allowDeclareFields: true,
+ onlyRemoveTypeImports: true,
+ },
+ ],
+ [
+ 'babel-plugin-ember-template-compilation',
+ {
+ transforms: [
+ ...(isCompat ? templateCompatSupport() : macros.templateMacros),
+ ],
+ },
+ ],
+ [
+ 'module:decorator-transforms',
+ {
+ runtime: {
+ import: require.resolve('decorator-transforms/runtime-esm'),
+ },
+ },
+ ],
+ ...(isCompat ? babelCompatSupport() : macros.babelMacros),
+ ],
+
+ generatorOpts: {
+ compact: false,
+ },
+};
diff --git a/packages/ember-hotkeys/babel.publish.config.cjs b/packages/ember-hotkeys/babel.publish.config.cjs
new file mode 100644
index 00000000..85ffa1d6
--- /dev/null
+++ b/packages/ember-hotkeys/babel.publish.config.cjs
@@ -0,0 +1,36 @@
+/**
+ * This babel.config is only used for publishing.
+ *
+ * For local dev experience, see the babel.config
+ */
+module.exports = {
+ plugins: [
+ [
+ '@babel/plugin-transform-typescript',
+ {
+ allExtensions: true,
+ allowDeclareFields: true,
+ onlyRemoveTypeImports: true,
+ },
+ ],
+ [
+ 'babel-plugin-ember-template-compilation',
+ {
+ targetFormat: 'hbs',
+ transforms: [],
+ },
+ ],
+ [
+ 'module:decorator-transforms',
+ {
+ runtime: {
+ import: 'decorator-transforms/runtime-esm',
+ },
+ },
+ ],
+ ],
+
+ generatorOpts: {
+ compact: false,
+ },
+};
diff --git a/packages/ember-hotkeys/config/ember-cli-update.json b/packages/ember-hotkeys/config/ember-cli-update.json
new file mode 100644
index 00000000..2c72c6f7
--- /dev/null
+++ b/packages/ember-hotkeys/config/ember-cli-update.json
@@ -0,0 +1,21 @@
+{
+ "schemaVersion": "1.0.0",
+ "projectName": "ember-hotkeys",
+ "packages": [
+ {
+ "name": "@ember/addon-blueprint",
+ "version": "0.17.1",
+ "blueprints": [
+ {
+ "name": "@ember/addon-blueprint",
+ "isBaseBlueprint": true,
+ "options": [
+ "--ci-provider=github",
+ "--pnpm",
+ "--typescript"
+ ]
+ }
+ ]
+ }
+ ]
+}
diff --git a/packages/ember-hotkeys/eslint.config.mjs b/packages/ember-hotkeys/eslint.config.mjs
new file mode 100644
index 00000000..8d8ae749
--- /dev/null
+++ b/packages/ember-hotkeys/eslint.config.mjs
@@ -0,0 +1,129 @@
+/**
+ * Debugging:
+ * https://eslint.org/docs/latest/use/configure/debug
+ * ----------------------------------------------------
+ *
+ * Print a file's calculated configuration
+ *
+ * npx eslint --print-config path/to/file.js
+ *
+ * Inspecting the config
+ *
+ * npx eslint --inspect-config
+ *
+ */
+import babelParser from '@babel/eslint-parser/experimental-worker';
+import js from '@eslint/js';
+import { defineConfig, globalIgnores } from 'eslint/config';
+import prettier from 'eslint-config-prettier';
+import ember from 'eslint-plugin-ember/recommended';
+import importPlugin from 'eslint-plugin-import';
+import n from 'eslint-plugin-n';
+import globals from 'globals';
+import ts from 'typescript-eslint';
+
+const esmParserOptions = {
+ ecmaFeatures: { modules: true },
+ ecmaVersion: 'latest',
+};
+
+const tsParserOptions = {
+ projectService: true,
+ tsconfigRootDir: import.meta.dirname,
+};
+
+export default defineConfig([
+ globalIgnores(['dist/', 'dist-*/', 'declarations/', 'coverage/', '!**/.*']),
+ js.configs.recommended,
+ prettier,
+ ember.configs.base,
+ ember.configs.gjs,
+ ember.configs.gts,
+ /**
+ * https://eslint.org/docs/latest/use/configure/configuration-files#configuring-linter-options
+ */
+ {
+ linterOptions: {
+ reportUnusedDisableDirectives: 'error',
+ },
+ },
+ {
+ files: ['**/*.js'],
+ languageOptions: {
+ parser: babelParser,
+ },
+ },
+ {
+ files: ['**/*.{js,gjs}'],
+ languageOptions: {
+ parserOptions: esmParserOptions,
+ globals: {
+ ...globals.browser,
+ },
+ },
+ },
+ {
+ files: ['**/*.{ts,gts}'],
+ languageOptions: {
+ parser: ember.parser,
+ parserOptions: tsParserOptions,
+ globals: {
+ ...globals.browser,
+ },
+ },
+ extends: [
+ ...ts.configs.recommendedTypeChecked,
+ // https://github.com/ember-cli/ember-addon-blueprint/issues/119
+ {
+ ...ts.configs.eslintRecommended,
+ files: undefined,
+ },
+ ember.configs.gts,
+ ],
+ },
+ {
+ files: ['src/**/*'],
+ plugins: {
+ import: importPlugin,
+ },
+ rules: {
+ // require relative imports use full extensions
+ 'import/extensions': ['error', 'always', { ignorePackages: true }],
+ },
+ },
+ /**
+ * CJS node files
+ */
+ {
+ files: ['**/*.cjs'],
+ plugins: {
+ n,
+ },
+
+ languageOptions: {
+ sourceType: 'script',
+ ecmaVersion: 'latest',
+ globals: {
+ ...globals.node,
+ },
+ },
+ },
+ /**
+ * ESM node files
+ */
+ {
+ files: ['**/*.mjs'],
+ plugins: {
+ n,
+ },
+
+ languageOptions: {
+ sourceType: 'module',
+ ecmaVersion: 'latest',
+ parserOptions: esmParserOptions,
+ globals: {
+ ...globals.node,
+ },
+ },
+ },
+]);
diff --git a/packages/ember-hotkeys/package.json b/packages/ember-hotkeys/package.json
new file mode 100644
index 00000000..0d91a61b
--- /dev/null
+++ b/packages/ember-hotkeys/package.json
@@ -0,0 +1,132 @@
+{
+ "name": "@tanstack/ember-hotkeys",
+ "version": "0.10.0",
+ "description": "Ember adapter for TanStack Hotkeys",
+ "author": "Tanner Linsley",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/TanStack/hotkeys.git",
+ "directory": "packages/ember-hotkeys"
+ },
+ "homepage": "https://tanstack.com/hotkeys",
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/sponsors/tannerlinsley"
+ },
+ "keywords": [
+ "ember",
+ "ember-addon",
+ "tanstack",
+ "hotkeys",
+ "keyboard",
+ "shortcuts"
+ ],
+ "imports": {
+ "#src/*": "./src/*"
+ },
+ "exports": {
+ ".": {
+ "types": "./declarations/index.d.ts",
+ "default": "./dist/index.js"
+ },
+ "./addon-main.js": "./addon-main.cjs",
+ "./test-support": {
+ "types": "./declarations/test-support.d.ts",
+ "default": "./dist/test-support.js"
+ },
+ "./*.css": "./dist/*.css",
+ "./*": {
+ "types": "./declarations/*.d.ts",
+ "default": "./dist/*.js"
+ }
+ },
+ "files": [
+ "addon-main.cjs",
+ "declarations",
+ "dist",
+ "src"
+ ],
+ "scripts": {
+ "build": "rollup --config",
+ "format": "prettier . --cache --write",
+ "lint": "concurrently \"pnpm:lint:*(!fix)\" --names \"lint:\" --prefixColors auto",
+ "lint:fix": "concurrently \"pnpm:lint:*:fix\" --names \"fix:\" --prefixColors auto && pnpm run format",
+ "lint:format": "prettier . --cache --check",
+ "lint:hbs": "ember-template-lint . --no-error-on-unmatched-pattern",
+ "lint:hbs:fix": "ember-template-lint . --fix --no-error-on-unmatched-pattern",
+ "lint:js": "eslint . --cache",
+ "lint:js:fix": "eslint . --fix",
+ "lint:publish": "pnpm build && publint run --level error",
+ "lint:types": "ember-tsc --noEmit",
+ "prepack": "rollup --config",
+ "start": "vite dev",
+ "test": "vite build --mode=development --out-dir dist-tests && testem --file testem.cjs ci --port 0"
+ },
+ "dependencies": {
+ "@embroider/addon-shim": "^1.8.9",
+ "@tanstack/hotkeys": "workspace:*",
+ "decorator-transforms": "^2.2.2"
+ },
+ "peerDependencies": {
+ "ember-source": ">=5.0.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^7.25.2",
+ "@babel/eslint-parser": "^7.25.1",
+ "@babel/plugin-transform-typescript": "^7.25.2",
+ "@babel/runtime": "^7.25.6",
+ "@ember/app-tsconfig": "^1.0.0",
+ "@ember/library-tsconfig": "^1.0.0",
+ "@ember/test-helpers": "^5.2.1",
+ "@ember/test-waiters": "^4.1.1",
+ "@embroider/addon-dev": "^8.1.0",
+ "@embroider/compat": "^4.1.0",
+ "@embroider/core": "^4.1.0",
+ "@embroider/macros": "^1.20.1",
+ "@embroider/vite": "^1.1.5",
+ "@eslint/js": "^9.17.0",
+ "@glimmer/component": "^2.0.0",
+ "@glint/ember-tsc": "^1.0.3",
+ "@glint/template": "^1.6.1",
+ "@glint/tsserver-plugin": "^2.0.0",
+ "@rollup/plugin-babel": "^6.0.4",
+ "@rollup/plugin-node-resolve": "^16.0.3",
+ "@types/qunit": "^2.19.12",
+ "babel-plugin-ember-template-compilation": "^4.0.0",
+ "concurrently": "^9.0.1",
+ "ember-page-title": "^9.0.3",
+ "ember-qunit": "^9.0.2",
+ "ember-source": "^6.7.0",
+ "ember-strict-application-resolver": "^0.1.0",
+ "ember-template-lint": "^7.9.0",
+ "eslint": "^10.2.1",
+ "eslint-config-prettier": "^10.1.5",
+ "eslint-plugin-ember": "^12.3.3",
+ "eslint-plugin-import": "^2.31.0",
+ "eslint-plugin-n": "^17.15.1",
+ "globals": "^16.1.0",
+ "prettier": "^3.8.3",
+ "prettier-plugin-ember-template-tag": "^2.0.4",
+ "publint": "^0.3.18",
+ "qunit": "^2.24.1",
+ "qunit-dom": "^3.4.0",
+ "rollup": "^4.22.5",
+ "testem": "^3.15.1",
+ "typescript": "6.0.3",
+ "typescript-eslint": "^8.19.1",
+ "vite": "^8.0.10"
+ },
+ "ember": {
+ "edition": "octane"
+ },
+ "ember-addon": {
+ "version": 2,
+ "type": "addon",
+ "main": "addon-main.cjs",
+ "app-js": {
+ "./helpers/on-hotkey-sequence.js": "./dist/_app_/helpers/on-hotkey-sequence.js",
+ "./helpers/on-hotkey.js": "./dist/_app_/helpers/on-hotkey.js"
+ }
+ }
+}
diff --git a/packages/ember-hotkeys/pnpm-workspace.yaml b/packages/ember-hotkeys/pnpm-workspace.yaml
new file mode 100644
index 00000000..fc24cf12
--- /dev/null
+++ b/packages/ember-hotkeys/pnpm-workspace.yaml
@@ -0,0 +1,9 @@
+# Docs: https://pnpm.io/settings
+# https://github.com/emberjs/rfcs/pull/907
+
+# we don't want addons to be bad citizens of the ecosystem
+autoInstallPeers: false
+
+# we want true isolation,
+# if a dependency is not declared, we want an error
+resolvePeersFromWorkspaceRoot: false
diff --git a/packages/ember-hotkeys/rollup.config.mjs b/packages/ember-hotkeys/rollup.config.mjs
new file mode 100644
index 00000000..8cc71c3b
--- /dev/null
+++ b/packages/ember-hotkeys/rollup.config.mjs
@@ -0,0 +1,80 @@
+import { babel } from '@rollup/plugin-babel'
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+import { Addon } from '@embroider/addon-dev/rollup'
+import { fileURLToPath } from 'node:url'
+import { resolve, dirname } from 'node:path'
+
+const addon = new Addon({
+ srcDir: 'src',
+ destDir: 'dist',
+})
+
+const rootDirectory = dirname(fileURLToPath(import.meta.url))
+const babelConfig = resolve(rootDirectory, './babel.publish.config.cjs')
+const tsConfig = resolve(rootDirectory, './tsconfig.publish.json')
+
+export default {
+ // This provides defaults that work well alongside `publicEntrypoints` below.
+ // You can augment this if you need to.
+ output: addon.output(),
+
+ plugins: [
+ // These are the modules that users should be able to import from your
+ // addon. Anything not listed here may get optimized away.
+ // By default all your JavaScript modules (**/*.js) will be importable.
+ // But you are encouraged to tweak this to only cover the modules that make
+ // up your addon's public API. Also make sure your package.json#exports
+ // is aligned to the config here.
+ // See https://github.com/embroider-build/embroider/blob/main/docs/v2-faq.md#how-can-i-define-the-public-exports-of-my-addon
+ addon.publicEntrypoints([
+ 'index.js',
+ 'helpers/**/*.js',
+ 'test-support.js',
+ 'template-registry.js',
+ ]),
+
+ // These are the modules that should get reexported into the traditional
+ // "app" tree. Things in here should also be in publicEntrypoints above, but
+ // not everything in publicEntrypoints necessarily needs to go here.
+ addon.appReexports(['helpers/**/*.js']),
+
+ // Follow the V2 Addon rules about dependencies. Your code can import from
+ // `dependencies` and `peerDependencies` as well as standard Ember-provided
+ // package names.
+ addon.dependencies(),
+
+ // Resolve .ts extensions for internal imports
+ nodeResolve({ extensions: ['.ts', '.gts', '.js', '.gjs'] }),
+
+ // This babel config should *not* apply presets or compile away ES modules.
+ // It exists only to provide development niceties for you, like automatic
+ // template colocation.
+ //
+ // By default, this will load the actual babel config from the file
+ // babel.config.json.
+ babel({
+ extensions: ['.js', '.gjs', '.ts', '.gts'],
+ babelHelpers: 'bundled',
+ configFile: babelConfig,
+ }),
+
+ // Ensure that standalone .hbs files are properly integrated as Javascript.
+ addon.hbs(),
+
+ // Ensure that .gjs files are properly integrated as Javascript
+ addon.gjs(),
+
+ // Emit .d.ts declaration files
+ addon.declarations(
+ 'declarations',
+ `pnpm ember-tsc --declaration --project ${tsConfig}`,
+ ),
+
+ // addons are allowed to contain imports of .css files, which we want rollup
+ // to leave alone and keep in the published output.
+ addon.keepAssets(['**/*.css']),
+
+ // Remove leftover build artifacts when starting a new build.
+ addon.clean(),
+ ],
+}
diff --git a/packages/ember-hotkeys/src/helpers/on-hotkey-sequence.ts b/packages/ember-hotkeys/src/helpers/on-hotkey-sequence.ts
new file mode 100644
index 00000000..cce41388
--- /dev/null
+++ b/packages/ember-hotkeys/src/helpers/on-hotkey-sequence.ts
@@ -0,0 +1,83 @@
+import Helper from '@ember/component/helper';
+import { getSequenceManager } from '@tanstack/hotkeys';
+import type {
+ HotkeyCallback,
+ HotkeySequence,
+ SequenceOptions,
+ SequenceRegistrationHandle,
+} from '@tanstack/hotkeys';
+
+export interface OnHotkeySequenceSignature {
+ Args: {
+ Positional: [sequence: HotkeySequence, callback: HotkeyCallback];
+ Named: OnHotkeySequenceOptions;
+ };
+ Return: void;
+}
+
+export interface OnHotkeySequenceOptions
+ extends Omit
+
+ 
+ |
+
+
+ 
+ |
+
+
+
+
+
++We're looking for TanStack Hotkeys Partners to join our mission! Partner with us to push the boundaries of TanStack Hotkeys and build amazing things together. +
+LET'S CHAT +
+
+
+
+
+
+
+
+
diff --git a/packages/ember-hotkeys/tests/integration/helpers/on-hotkey-sequence-test.gts b/packages/ember-hotkeys/tests/integration/helpers/on-hotkey-sequence-test.gts
new file mode 100644
index 00000000..80ae8378
--- /dev/null
+++ b/packages/ember-hotkeys/tests/integration/helpers/on-hotkey-sequence-test.gts
@@ -0,0 +1,157 @@
+import { module, test } from 'qunit';
+import { render, settled } from '@ember/test-helpers';
+import { setupRenderingTest } from 'ember-qunit';
+import { HotkeyManager, SequenceManager } from '@tanstack/hotkeys';
+import onHotkeySequence from '@tanstack/ember-hotkeys/helpers/on-hotkey-sequence';
+import { array } from '@ember/helper';
+
+module('Integration | Helper | on-hotkey-sequence', function (hooks) {
+ setupRenderingTest(hooks);
+
+ hooks.beforeEach(function () {
+ HotkeyManager.resetInstance();
+ SequenceManager.resetInstance();
+ });
+
+ hooks.afterEach(function () {
+ HotkeyManager.resetInstance();
+ SequenceManager.resetInstance();
+ });
+
+ test('it registers a sequence handler', async function (assert) {
+ const callback = () => {};
+
+ await render(
+
+ {{onHotkeySequence (array "G" "G") callback}}
+ ,
+ );
+
+ const manager = SequenceManager.getInstance();
+ assert.strictEqual(
+ manager.getRegistrationCount(),
+ 1,
+ 'sequence is registered',
+ );
+ });
+
+ test('it calls callback when sequence matches', async function (assert) {
+ assert.expect(1);
+
+ const callback = () => assert.ok(true, 'sequence callback was called');
+
+ await render(
+
+ {{onHotkeySequence (array "G" "G") callback}}
+ ,
+ );
+
+ document.dispatchEvent(
+ new KeyboardEvent('keydown', {
+ key: 'g',
+ bubbles: true,
+ }),
+ );
+ document.dispatchEvent(
+ new KeyboardEvent('keydown', {
+ key: 'g',
+ bubbles: true,
+ }),
+ );
+ });
+
+ test('it does not call callback for partial sequence', async function (assert) {
+ let callCount = 0;
+ const callback = () => callCount++;
+
+ await render(
+
+ {{onHotkeySequence (array "D" "I" "W") callback}}
+ ,
+ );
+
+ document.dispatchEvent(
+ new KeyboardEvent('keydown', {
+ key: 'd',
+ bubbles: true,
+ }),
+ );
+ document.dispatchEvent(
+ new KeyboardEvent('keydown', {
+ key: 'i',
+ bubbles: true,
+ }),
+ );
+
+ assert.strictEqual(callCount, 0, 'callback not called for partial sequence');
+ });
+
+ test('it unregisters on teardown', async function (assert) {
+ const callback = () => {};
+
+ await render(
+
+ {{onHotkeySequence (array "G" "G") callback}}
+ ,
+ );
+
+ const manager = SequenceManager.getInstance();
+ assert.strictEqual(
+ manager.getRegistrationCount(),
+ 1,
+ 'sequence is registered',
+ );
+
+ await render();
+ await settled();
+
+ assert.strictEqual(
+ manager.getRegistrationCount(),
+ 0,
+ 'sequence is unregistered after teardown',
+ );
+ });
+
+ test('it supports the enabled option', async function (assert) {
+ let callCount = 0;
+ const callback = () => callCount++;
+
+ await render(
+
+ {{onHotkeySequence (array "G" "G") callback enabled=false}}
+ ,
+ );
+
+ document.dispatchEvent(
+ new KeyboardEvent('keydown', {
+ key: 'g',
+ bubbles: true,
+ }),
+ );
+ document.dispatchEvent(
+ new KeyboardEvent('keydown', {
+ key: 'g',
+ bubbles: true,
+ }),
+ );
+
+ assert.strictEqual(callCount, 0, 'callback is not called when disabled');
+ });
+
+ test('it handles empty sequence as no-op', async function (assert) {
+ const callback = () => {};
+
+ await render(
+
+ {{onHotkeySequence (array) callback}}
+ ,
+ );
+
+ const manager = SequenceManager.getInstance();
+ assert.strictEqual(
+ manager.getRegistrationCount(),
+ 0,
+ 'empty sequence is not registered',
+ );
+ });
+});
diff --git a/packages/ember-hotkeys/tests/integration/helpers/on-hotkey-test.gts b/packages/ember-hotkeys/tests/integration/helpers/on-hotkey-test.gts
new file mode 100644
index 00000000..c4c47d1d
--- /dev/null
+++ b/packages/ember-hotkeys/tests/integration/helpers/on-hotkey-test.gts
@@ -0,0 +1,185 @@
+import { module, test } from 'qunit';
+import { render, settled } from '@ember/test-helpers';
+import { setupRenderingTest } from 'ember-qunit';
+import { HotkeyManager } from '@tanstack/hotkeys';
+import onHotkey from '@tanstack/ember-hotkeys/helpers/on-hotkey';
+
+module('Integration | Helper | on-hotkey', function (hooks) {
+ setupRenderingTest(hooks);
+
+ hooks.beforeEach(function () {
+ HotkeyManager.resetInstance();
+ });
+
+ hooks.afterEach(function () {
+ HotkeyManager.resetInstance();
+ });
+
+ test('it registers a hotkey handler', async function (assert) {
+ const addEventListenerSpy = sinon(document, 'addEventListener');
+
+ const callback = () => {};
+
+ await render(
+
+ {{onHotkey "Mod+S" callback platform="mac"}}
+ ,
+ );
+
+ assert.true(
+ addEventListenerSpy.calls.some(
+ (call: { args: Array
+
+
+