TanStack Hotkeys in Ember
Before starting, load the @tanstack/hotkeys#hotkeys-core skill (npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core).
import Component from '@glimmer/component'
import { tracked } from '@glimmer/tracking'
import { array } from '@ember/helper'
import { onHotkey, useHotkey } from '@tanstack/ember-hotkeys'
export default class Editor extends Component {
@tracked dirty = false
save = () => saveDocument()
close = () => closePanel()
scrollToTop = () => window.scrollTo({ top: 0 })
<template>
{{useHotkey "Mod+S" this.save enabled=this.dirty}}
{{useHotkey (array "G" "G") this.scrollToTop}}
<div tabindex="0" {{onHotkey "Escape" this.close}}>Panel</div>
</template>
}
API
| API |
What it's for |
{{useHotkey hotkey callback ...options}} |
Register one chord, sequence, or app hotkey while the template renders the helper. |
{{useHotkeys definitions}} |
Register several hotkeys, or a list built from data, in one helper. |
{{onHotkey hotkey callback ...options}} |
Attach a hotkey to the element the modifier is on, so it fires while focus is inside that element. |
{{onHotkeys definitions}} |
Attach several hotkeys to one element. |
createHotkeysScope(defaults?) |
Create useHotkey, useHotkeys, onHotkey, and onHotkeys that share default options. |
useFormatForDisplay(scope?) |
Get formatForDisplay with the scope's platform filled in, for labels rendered by FastBoot. |
provideAppHotkeys(appHotkeys, options?) |
Declare app hotkeys and load the user's custom hotkeys before the app boots, since Ember has no provider. |
getHotkeyManager().activateScope(scope, options?) |
Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off. |
useAppHotkeys(this) |
Get the declared app hotkeys with the user's custom hotkeys applied. |
useAppHotkeyList(this) |
List every app hotkey with its status, for a cheat sheet or settings screen. |
useCustomHotkeys(this) |
Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |
useHotkeyRecorder(this, options, scope?) |
Record a chord or sequence the user presses, for a settings screen. Pass a createHotkeysScope result to apply its hotkeyRecorder defaults. |
useHotkeyRegistrations(this) |
Read .hotkeys, every registered hotkey with its options, meta, and status (whether it's enabled and in an active scope). |
useHotkeyScopesState(this) |
Get the active scopes and the exclusive scope that owns the keyboard. |
useHotkeyHint(this, hotkey, options?) |
Get whether held modifiers should reveal a shortcut's hint. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |
useKeyHold(this, key) |
Get whether one key is held. Letters match in any case; other names, such as Shift, are case-sensitive. |
useHeldKeys(this) |
Get every key that's held right now. |
useHeldKeyCodes(this) |
Map each held key to its physical event.code. |
The package also re-exports @tanstack/hotkeys, such as formatForDisplay, matchesKeyboardEvent, and defineAppHotkeys.
The helpers are template helpers, not JavaScript functions. State readers take the component as their owner, and their state is read through .value, or .hotkeys for registrations. Use Ember 6.8.3 or newer, except 6.9.0 and 6.10.0, and strict-mode .gts components.
Pitfalls
- Use arrow-function fields, or
@action, for callbacks. The helpers call a callback without the component as this, so a plain method throws when the key is pressed.
- Build template sequences with
array. {{useHotkey "G G" ...}} registers a single key named G G, which never matches.
createHotkeysScope isn't a hotkey scope. It only sets defaults for its helpers. For a dialog, call getHotkeyManager().activateScope(name, { exclusive: true }) in the constructor, pass the result to registerDestructor(this, release), and put scope=name on the dialog's hotkeys. Give each open dialog its own name.
- Read app hotkeys through getters. Template paths can't index ids that contain dots.
- Scopes have no
useHotkeyRecorder since v0.9.0. Call useHotkeyRecorder(this, options, this.hotkeys), so apps that set defaults but don't record don't ship the recorder.
- Server-rendered labels need the user's platform. On the server,
formatForDisplay can't see the user's OS, so it renders Linux labels that differ after hydration for Mac and Windows users. Pass platform: detectPlatform(userAgent) to createHotkeysScope, with the user agent from FastBoot's request, and format labels with format = useFormatForDisplay(this.hotkeys), then {{this.format hotkey}}. Keep plain formatForDisplay for labels that render only in the browser, when no scope sets platform.
When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load @tanstack/hotkeys#app-hotkeys and read app hotkeys in Ember.
API discovery and docs
Signatures: node_modules/@tanstack/ember-hotkeys/dist/*.d.ts, with state shapes in types.d.ts. Guides: https://tanstack.com/hotkeys/latest/docs/framework/ember/guides/<page>.md, such as hotkeys or app-hotkeys.
1---2name: tanstack-ember-hotkeys3description: "Use when adding or fixing keyboard shortcuts in an Ember app with @tanstack/ember-hotkeys: the useHotkey and useHotkeys template helpers, onHotkey and onHotkeys element modifiers, createHotkeysScope defaults, scopes activated from the hotkey manager, app hotkeys, recorders, and held keys in strict-mode .gts components, or replacing keydown event listeners."4license: "MIT"5metadata:6 source: https://skillmd.com/skills/lukasa1993/tanstack-ember-hotkeys7 internal: true8 tanstack-framework: "ember"9 tanstack-library: "@tanstack/ember-hotkeys"10 tanstack-library-version: "0.4.0"11 tanstack-package: "@tanstack/ember-hotkeys"12 tanstack-package-version: "0.11.1"13 tanstack-purpose: "Ember bindings for TanStack Hotkeys: template helpers, element modifiers, owner-bound state readers, manager-activated scopes, and the Ember-specific mistakes to avoid."14 tanstack-requires: "[\"tanstack-hotkeys-core\"]"15 tanstack-source-skill: "ember-hotkeys"16 tanstack-sources: "[\"src/useHotkey.ts\",\"src/useHotkeys.ts\",\"src/onHotkey.ts\",\"src/onHotkeys.ts\",\"src/createHotkeysScope.ts\",\"src/useHotkeyRecorder.ts\",\"src/useAppHotkeys.ts\",\"TanStack/hotkeys:docs/framework/ember/quick-start.md\",\"TanStack/hotkeys:docs/framework/ember/guides/app-hotkeys.md\"]"17 tanstack-type: "framework"18---1920# TanStack Hotkeys in Ember2122Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).2324```gts25import Component from '@glimmer/component'26import { tracked } from '@glimmer/tracking'27import { array } from '@ember/helper'28import { onHotkey, useHotkey } from '@tanstack/ember-hotkeys'2930export default class Editor extends Component {31 @tracked dirty = false32 save = () => saveDocument()33 close = () => closePanel()34 scrollToTop = () => window.scrollTo({ top: 0 })3536 <template>37 {{useHotkey "Mod+S" this.save enabled=this.dirty}}38 {{useHotkey (array "G" "G") this.scrollToTop}}39 <div tabindex="0" {{onHotkey "Escape" this.close}}>Panel</div>40 </template>41}42```4344## API4546| API | What it's for |47| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |48| `{{useHotkey hotkey callback ...options}}` | Register one chord, sequence, or app hotkey while the template renders the helper. |49| `{{useHotkeys definitions}}` | Register several hotkeys, or a list built from data, in one helper. |50| `{{onHotkey hotkey callback ...options}}` | Attach a hotkey to the element the modifier is on, so it fires while focus is inside that element. |51| `{{onHotkeys definitions}}` | Attach several hotkeys to one element. |52| `createHotkeysScope(defaults?)` | Create `useHotkey`, `useHotkeys`, `onHotkey`, and `onHotkeys` that share default options. |53| `useFormatForDisplay(scope?)` | Get `formatForDisplay` with the scope's `platform` filled in, for labels rendered by FastBoot. |54| `provideAppHotkeys(appHotkeys, options?)` | Declare app hotkeys and load the user's custom hotkeys before the app boots, since Ember has no provider. |55| `getHotkeyManager().activateScope(scope, options?)` | Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off. |56| `useAppHotkeys(this)` | Get the declared app hotkeys with the user's custom hotkeys applied. |57| `useAppHotkeyList(this)` | List every app hotkey with its status, for a cheat sheet or settings screen. |58| `useCustomHotkeys(this)` | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts. |59| `useHotkeyRecorder(this, options, scope?)` | Record a chord or sequence the user presses, for a settings screen. Pass a `createHotkeysScope` result to apply its `hotkeyRecorder` defaults. |60| `useHotkeyRegistrations(this)` | Read `.hotkeys`, every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope). |61| `useHotkeyScopesState(this)` | Get the active scopes and the exclusive scope that owns the keyboard. |62| `useHotkeyHint(this, hotkey, options?)` | Get whether held modifiers should reveal a shortcut's hint. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |63| `useKeyHold(this, key)` | Get whether one key is held. Letters match in any case; other names, such as `Shift`, are case-sensitive. |64| `useHeldKeys(this)` | Get every key that's held right now. |65| `useHeldKeyCodes(this)` | Map each held key to its physical `event.code`. |6667The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.6869The helpers are template helpers, not JavaScript functions. State readers take the component as their owner, and their state is read through `.value`, or `.hotkeys` for registrations. Use Ember 6.8.3 or newer, except 6.9.0 and 6.10.0, and strict-mode `.gts` components.7071## Pitfalls7273- **Use arrow-function fields, or `@action`, for callbacks.** The helpers call a callback without the component as `this`, so a plain method throws when the key is pressed.74- **Build template sequences with `array`.** `{{useHotkey "G G" ...}}` registers a single key named `G G`, which never matches.75- **`createHotkeysScope` isn't a hotkey scope.** It only sets defaults for its helpers. For a dialog, call `getHotkeyManager().activateScope(name, { exclusive: true })` in the constructor, pass the result to `registerDestructor(this, release)`, and put `scope=name` on the dialog's hotkeys. Give each open dialog its own name.76- **Read app hotkeys through getters.** Template paths can't index ids that contain dots.77- **Scopes have no `useHotkeyRecorder`** since v0.9.0. Call `useHotkeyRecorder(this, options, this.hotkeys)`, so apps that set defaults but don't record don't ship the recorder.78- **Server-rendered labels need the user's platform.** On the server, `formatForDisplay` can't see the user's OS, so it renders Linux labels that differ after hydration for Mac and Windows users. Pass `platform: detectPlatform(userAgent)` to `createHotkeysScope`, with the user agent from FastBoot's request, and format labels with `format = useFormatForDisplay(this.hotkeys)`, then `{{this.format hotkey}}`. Keep plain `formatForDisplay` for labels that render only in the browser, when no scope sets `platform`.7980When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Ember](./references/app-hotkeys.md).8182## API discovery and docs8384Signatures: `node_modules/@tanstack/ember-hotkeys/dist/*.d.ts`, with state shapes in `types.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/ember/guides/<page>.md`, such as `hotkeys` or `app-hotkeys`.