+```
+
+An app hotkey registered by many components, such as one per list row, appears once. Its `registrations` array holds each live registration. Devtools also list declared app hotkeys that are not registered.
+
+## Customize and persist hotkeys
+
+TanStack Hotkeys does not store anything. Pass the user's saved custom hotkeys in and save them when they change:
+
+```svelte
+
+
+
+ localStorage.setItem('hotkeys', JSON.stringify(custom))}
+>
+
+
+```
+
+`setHotkeysContext` accepts the same `appHotkeys`, `customHotkeys`, and `onCustomHotkeysChange` options.
+
+- `customHotkeys` holds only the hotkeys that differ from the declared defaults, keyed by id. `null` means the user unbound that hotkey. Saving differences means users who never changed a hotkey get new defaults when you change them.
+- `customHotkeys` is read once; afterwards the shared store owns the state. Saved data can outlive the code that wrote it, so unknown ids and invalid hotkeys are ignored with a warning.
+- `onCustomHotkeysChange` receives the complete custom hotkeys after every change, ready to save. Storage can be anything: local storage, a server, or a user profile.
+
+Recorded hotkeys use `Mod` rather than platform-specific modifiers, so a hotkey saved on one platform works on others.
+
+### Change hotkeys
+
+`getCustomHotkeys` reads and changes the user's custom hotkeys:
+
+```svelte
+
+
+
+```
+
+| Member | Description |
+| --- | --- |
+| `current` | The hotkeys that differ from the defaults |
+| `setCustomHotkey(id, hotkey)` | Sets a hotkey, or unbinds with `null`. Returns conflicting app hotkeys; when there are any, nothing changes. |
+| `findConflicts(id, hotkey)` | App hotkeys that would collide if `id` used `hotkey` |
+| `resetCustomHotkey(id)` | Restores one default |
+| `resetCustomHotkeys()` | Restores every default |
+
+Two app hotkeys conflict when their contexts match or either has no `context`, and their hotkeys collide: equal chords, or one sequence starts with the other, including a sequence whose first step equals a chord. Conflicts are checked across every declaration, whether or not it is registered.
+
+Each app hotkey's `defaultHotkey` holds its declared default, and each cheat sheet item's `isCustom` reports whether the effective hotkey differs from it.
diff --git a/docs/framework/svelte/guides/formatting-display.md b/docs/framework/svelte/guides/formatting-display.md
index f7e4a8fa..c050a311 100644
--- a/docs/framework/svelte/guides/formatting-display.md
+++ b/docs/framework/svelte/guides/formatting-display.md
@@ -3,7 +3,7 @@ title: Formatting & Display Guide
id: formatting-display
---
-Use `formatForDisplay` whenever a binding appears in a menu, button, hint, or shortcut settings panel. It accepts logical strings, bracketed physical strings, raw objects, and parsed bindings. Store the original binding and format it at render time: the display label is not a registration string.
+Use `formatForDisplay` whenever a hotkey appears in a menu, button, hint, cheat sheet, or shortcut settings panel. It accepts logical strings, bracketed physical strings, raw objects, parsed bindings, and sequences. Store the original binding and format it at render time: the display label is not a registration string.
## Format a binding
@@ -32,16 +32,18 @@ const parts = formatForDisplay(binding, { platform: 'mac', parts: true })
With `parts` omitted or false, the result is a string. A runtime boolean returns `string | string[]`. Parts preserve literal plus keys and ignore `separatorToken`.
-Sequences are arrays of bindings. Format their steps individually:
+## Format sequences
-```ts
-import type { HotkeySequence } from '@tanstack/svelte-hotkeys'
+Pass a sequence to format each step and join the steps with `sequenceSeparator`, a space by default:
-const sequence: HotkeySequence = ['Mod+[KeyK]', 'C']
-const label = sequence.map((step) => formatForDisplay(step)).join(' → ')
+```ts
+formatForDisplay(['Mod+[KeyK]', 'C'], { platform: 'mac' }) // '⌘ K C'
+formatForDisplay(['G', 'G'], { sequenceSeparator: ' → ' }) // 'G → G'
+formatForDisplay(['Mod+[KeyK]', 'C'], { platform: 'mac', parts: true })
+// [['⌘', 'K'], ['C']] — one array of keycaps per step
```
-`formatHotkeySequence` only joins stored strings with spaces. It intentionally retains brackets and code names, so use the code above for user-facing labels.
+With `parts: true`, a sequence returns one array per step, so you can render each step as a group of keycaps.
## Choose symbols and separators
@@ -63,7 +65,7 @@ formatForDisplay('Control++', {
}) // 'Ctrl · +'
```
-An empty separator joins labels directly. `undefined` or `null` uses the platform default. `formatWithLabels(binding, options)` is the shorthand for `formatForDisplay` with `useSymbols: false`.
+An empty separator joins labels directly. `undefined` or `null` uses the platform default. `separatorToken` applies within a chord; `sequenceSeparator` applies between steps.
## Supply layout labels
@@ -88,6 +90,10 @@ formatForDisplay('Mod+[KeyQ]', {
The precedence is `keyLabels`, then a layout entry, then the fallback label. Layout entries receive normal letter casing and key symbols; missing or empty entries fall back. Explicit labels are final. All of these options affect display only.
+## Compare hotkeys
+
+`areHotkeysEqual(a, b)` compares chords or sequences after resolving modifiers, so `Mod+S` equals `Meta+S` on macOS. Sequences compare step by step. `isHotkeySequence` narrows a `Hotkey` to a sequence, and `simplifyHotkey` turns a one-step sequence into its chord.
+
## Parse and store bindings
`parseHotkey` returns either a logical `key` or a physical `code`, plus resolved modifier flags. Narrow the union before inspecting the identity:
@@ -105,6 +111,6 @@ formatForDisplay(stored, { platform: 'windows' }) // 'Ctrl+S'
Parsed modifiers are already resolved. To display a portable `Mod` binding on another platform, serialize with the original platform first, as above. `normalizeRegisterableHotkey` accepts strings or raw objects and preserves the logical/physical distinction. Do not store display labels or put a bracketed code in a logical `key` field.
-Use `validateHotkey` when accepting strings from an external source. It returns `valid`, `errors`, and `warnings`; it does not guarantee that a browser or operating system will deliver the shortcut. Recorder validation and live conflict checks are covered in the [recording guide](./hotkey-recording.md#validation-and-conflicts).
+Use `validateHotkey` when accepting a chord or sequence from an external source. It returns `valid`, `errors`, and `warnings`, and names the failing step of a sequence; it does not guarantee that a browser or operating system will deliver the shortcut. Recorder validation and live conflict checks are covered in the [recording guide](./hotkey-recording.md#validation-and-conflicts).
Try these options together in the [vanilla formatter playground](../../../framework/vanilla/examples/formatForDisplay).
diff --git a/docs/framework/svelte/guides/hotkey-recording.md b/docs/framework/svelte/guides/hotkey-recording.md
index 57608648..70bcf8c4 100644
--- a/docs/framework/svelte/guides/hotkey-recording.md
+++ b/docs/framework/svelte/guides/hotkey-recording.md
@@ -3,114 +3,131 @@ title: Hotkey Recording Guide
id: hotkey-recording
---
-TanStack Hotkeys provides the `createHotkeyRecorder` function for building shortcut customization UIs in Svelte.
+`createHotkeyRecorder` is for building keyboard shortcut customization UIs. Users record their own shortcuts by pressing the key combination they want, the same way system preferences or IDE shortcut editors work. By default it records one chord; set `maxSteps` to let users record a [sequence](./sequences) too.
Recorders default to physical codes: recording a shortcut stores a string such as `Mod+[KeyS]`. Pass it directly to your hotkey registration and use `formatForDisplay` for the label. Set `recordBy: 'key'` when you intentionally want the produced character instead.
-TanStack Hotkeys automatically suppresses registered hotkey and sequence callbacks while any recorder is active. You do not need to set `enabled` from `isRecording`. Registrations remain available for conflict detection, and recorded keys stay suppressed through repeats and key release.
-
-## Reactive options
-
-Recorder options support [property getters and functions returning options](./hotkeys.md#property-getters). Updated callbacks, validation, and recording settings apply during an active session without restarting it. Allow the framework to run its effect or watcher before relying on the update.
+TanStack Hotkeys automatically suppresses registered hotkey callbacks while any recorder is active. You do not need to disable hotkeys while recording. Registrations remain available for conflict detection, and recorded keys stay suppressed through repeats and key release.
## Basic usage
```svelte
-
-
- {#if recorder.isRecording}
-
- {/if}
-
+
```
-## Return value
+## Recorder state and actions
+
+| Member | Description |
+| --- | --- |
+| `isRecording` | Whether the recorder is currently listening for key presses |
+| `steps` | Chords captured so far in a multi-step recording |
+| `recordedHotkey` | The last recorded hotkey, or `null` if nothing recorded |
+| `startRecording()` | Start listening for key presses |
+| `stopRecording()` | Stop listening without calling `onRecord` or `onCancel` |
+| `cancelRecording()` | Stop listening and call `onCancel` |
+| `commitRecording()` | Commit the current `steps` now (multi-step recordings) |
-- `isRecording`: whether recording is active
-- `recordedHotkey`: the most recently recorded hotkey
-- `startRecording()`: start listening for key presses
-- `stopRecording()`: stop listening and reset recorder state without calling `onRecord`
-- `cancelRecording()`: stop listening and discard the in-progress recording
+State members are reactive getters. Read them from the recorder object instead of destructuring them once.
## Options
### `recordBy`
-Recorders default to `recordBy: 'code'`. Option+S producing `ß` on macOS records `Alt+[KeyS]`; Option+2 producing `™` records `Alt+[Digit2]`. The stored brackets preserve physical identity through state, serialization, and registration; `formatForDisplay` produces a readable label. There is no code-to-letter conversion. Existing authored strings such as `Mod+S` remain logical bindings.
+Recorders default to `recordBy: 'code'`. Option+S producing `ß` on macOS records `Alt+[KeyS]`; Option+2 producing `™` records `Alt+[Digit2]`. The stored brackets preserve physical identity through state, serialization, and registration; `formatForDisplay` produces a readable label. Existing authored strings such as `Mod+S` remain logical hotkeys.
-Set `recordBy: 'key'` to intentionally record the produced logical character. A code-mode event with no usable code is rejected rather than silently switching modes. IME composition is ignored. AltGraph character entry is rejected in code mode; key mode preserves the produced character without synthetic Control/Alt while retaining Shift. Recording events, repeats, and their releases do not trigger registered hotkeys or sequences.
+Set `recordBy: 'key'` to intentionally record the produced logical character. A code-mode event with no usable code is rejected rather than silently switching modes. IME composition is ignored. AltGraph character entry is rejected in code mode; key mode preserves the produced character without synthetic Control/Alt while retaining Shift.
-```ts
-createHotkeyRecorder({
- recordBy: 'code', // default; choose 'key' for logical characters
- onRecord: (hotkey) => {},
- onCancel: () => {},
- onClear: () => {},
-})
-```
+### `onRecord`
-Options can also be reactive:
+Called when a recording commits. With the default `maxSteps: 1`, it receives a chord string such as `'Mod+[KeyS]'` as soon as the user presses a valid combination (a modifier + a non-modifier key, or a single non-modifier key). With a larger `maxSteps`, it receives a chord when one step was recorded, or a sequence otherwise.
-```svelte
-
-```
+### `onClear`
+
+Called when the recording is cleared: Backspace or Delete with no modifiers and no recorded steps. Clearing calls only `onClear`; your app decides whether that removes a hotkey or restores a default.
### `ignoreInputs`
-The `HotkeyRecorderOptions` supports an `ignoreInputs` option (defaults to `true`). When `true`, the recorder doesn't 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.
+Defaults to `true`. The recorder doesn't intercept normal typing in text inputs, textareas, selects, or contentEditable elements; keystrokes pass through to the input as usual. Escape still cancels recording even while an input is focused. Set `ignoreInputs: false` to record from inside input elements.
+
+Options can also be a getter, such as `createHotkeyRecorder(() => ({ maxSteps: 3, recordBy: mode, onRecord }))`, so recording policy can follow `$state`.
+
+### Default options
+
+Set defaults for every recorder with `HotkeysProvider` (or `setHotkeysContext` in a root component's script). Per-recorder options override them.
+
+```svelte
+
+
+
+```
+
+## Recording sequences
+
+Set `maxSteps` above 1 to record up to that many chords. Each chord adds a step, and the recording commits when the user presses Enter, when it reaches `maxSteps`, or after `idleTimeoutMs` without a new step:
```ts
-createHotkeyRecorder({
- ignoreInputs: false, // record even from inside inputs
- onRecord: (hotkey) => console.log(hotkey),
+const recorder = createHotkeyRecorder({
+ maxSteps: 3,
+ onRecord: (hotkey) => console.log('Recorded:', hotkey), // 'Mod+[KeyS]' or ['[KeyG]', '[KeyG]']
})
+
+// Live preview while recording
+const label = $derived(
+ recorder.isRecording
+ ? formatForDisplay(recorder.steps) || 'Press chords, then Enter…'
+ : formatForDisplay(recorder.recordedHotkey ?? []),
+)
```
+A one-step recording commits as a chord, so the result can always be passed straight to your hotkey registration. Use `maxSteps: Infinity` for no limit.
+
+| Option | Description |
+| --- | --- |
+| `maxSteps` | Maximum chords to record. Reaching it commits. Default `1`. |
+| `commitKeys` | `'enter'` (default) commits on plain Enter. With `'none'`, plain Enter can be recorded as a step, and only `commitRecording()`, `idleTimeoutMs`, or `maxSteps` commit. |
+| `idleTimeoutMs` | Commit automatically after this many milliseconds without a new step. The timer does not run before the first chord. |
+
+`commitKeys` and `idleTimeoutMs` are only accepted when `maxSteps` is set. With `maxSteps` above 1, `onRecord` and `validate` receive `Hotkey` (a chord or a sequence) instead of a chord.
+
## Recording behavior
-- Modifier-only presses do not complete a recording.
-- Modifier plus key combinations record the full shortcut.
-- Escape cancels recording.
-- Backspace and Delete clear the shortcut.
-- Recorded values are normalized to portable `Mod` format.
+| Key | Behavior |
+| --- | --- |
+| Modifier only (Shift, Ctrl, etc.) | Waits for a non-modifier key; modifier-only presses don't complete a step |
+| Modifier + key (e.g., Ctrl+S) | Records the full combination |
+| Single key (e.g., Escape, F1) | Records the single key |
+| Enter (multi-step, `commitKeys: 'enter'`) | Commits the recorded steps |
+| Escape | Cancels the recording |
+| Backspace / Delete | Removes the last step; with no steps, clears and calls `onClear` |
+
+Repeats and IME composition never add a step. Recorded hotkeys use the portable `Mod` format: Command+S on macOS records `Mod+[KeyS]` rather than `Meta+[KeyS]`, so the primary modifier becomes Control if the hotkey is later used on Windows.
## Validation and conflicts
-Both recorder APIs accept `detectConflicts`, `validate`, and `onReject`. For a single-hotkey recorder, these options can be supplied alongside `onRecord`:
+The recorder accepts `detectConflicts`, `validate`, and `onReject` alongside `onRecord`:
```ts
const options = {
detectConflicts: {
- // Use registration IDs to exclude the binding being edited:
+ // Use registration IDs to exclude the hotkey being edited:
excludeIds: [registrationId],
target: document,
eventType: 'keydown',
@@ -124,8 +141,62 @@ const options = {
}
```
-`validate` returns true to accept, or false/a message to reject. `onReject` receives `reason` (`missing-code`, `alt-graph`, `invalid`, `validation`, or `conflict`), a message, the candidate when available, and conflicting registration views for conflict rejections. Validation runs before commit; rejection never falls back to another key identity.
+`validate(hotkey, context)` returns true to accept, or false/a message to reject. The context holds the last chord's `event` and `parsedHotkey`, plus `events` and `parsedSequence` for every step. `onReject` receives `reason` (`missing-code`, `alt-graph`, `invalid`, `validation`, or `conflict`), a message, the rejected `hotkey` when available, and conflicting registrations for conflict rejections. Validation runs before commit; rejection never falls back to another key identity. A rejected multi-step recording keeps its steps so the user can edit them with Backspace.
+
+`detectConflicts: true` checks enabled live registrations with the intended event type (default keydown) and overlapping targets (default document). Document/nested scopes can conflict; disjoint widgets can reuse a hotkey. The options object also supports `scope: 'all'`, `includeDisabled`, and an `exclude(registration)` predicate. Chords and sequence prefixes are checked: a recorded chord conflicts with a sequence that starts with it, and a recorded sequence conflicts with a registered chord equal to its first step. Source events detect physical/logical overlap on the recorded layout. This is a conservative collision check, not a promise that two callbacks will execute.
+
+For checks outside recording, use `findHotkeyConflicts(hotkey, options)`. Without source `events`, it compares hotkey identity and sequence prefixes; it does not guess equivalence between a logical character and a physical position.
+
+## Building a shortcut settings UI
+
+For an app-wide settings screen, declare the hotkeys with [app hotkeys](./app-hotkeys) and save the recorder's result with `setCustomHotkey`. That keeps cheat sheets, conflicts, and persistence in one place.
+
+For a single component, ordinary state is enough:
+
+```svelte
+
+
+{#each Object.entries(shortcuts) as [action, hotkey] (action)}
+
+{/each}
+```
-`detectConflicts: true` checks enabled live registrations with the intended event type (default keydown) and overlapping targets (default document). Document/nested scopes can conflict; disjoint widgets can reuse a binding. The options object also supports `scope: 'all'`, `includeDisabled`, and an `exclude(registration)` predicate. Both single bindings and sequence prefixes are checked. Source events detect physical/logical overlap on the recorded layout. This is a conservative collision check, not a promise that two callbacks will execute: propagation, input filtering, match priority, external listeners, unmounted routes, and other layouts can affect actual dispatch.
+## Under the hood
-For checks outside recording, use `findHotkeyConflicts(bindingOrSequence, options)`. Without source `events`, it compares binding identity and sequence prefixes; it does not guess equivalence between a logical character and a physical position.
+`createHotkeyRecorder` creates a `HotkeyRecorder` from `@tanstack/hotkeys`, exposes its state through reactive getters, and destroys it when the component unmounts.
diff --git a/docs/framework/svelte/guides/hotkeys.md b/docs/framework/svelte/guides/hotkeys.md
index 66fa0f1b..241ded19 100644
--- a/docs/framework/svelte/guides/hotkeys.md
+++ b/docs/framework/svelte/guides/hotkeys.md
@@ -5,6 +5,18 @@ id: hotkeys
Use `createHotkey` for global shortcuts and `createHotkeyAttachment` for element-scoped shortcuts. The common global case stays simple, and scoped behavior feels native to Svelte 5.
+## Chords and sequences
+
+A hotkey is either a **chord**, keys pressed together such as `'Mod+S'`, or a **sequence**, chords pressed one after another such as `['G', 'G']`. Every API in this guide accepts both, and a one-step array such as `['Mod+S']` is the chord `'Mod+S'`.
+
+```ts
+createHotkey('Mod+S', () => save()) // chord
+createHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 }) // sequence
+createHotkey('Escape', () => close(), { requireReset: true }) // chord-only option
+```
+
+Most options apply to both kinds. `requireReset` applies only to chords and `timeout` only to sequences, and TypeScript rejects options that don't match the hotkey. When the kind isn't known statically, such as a `Hotkey` loaded from settings, only the shared options are accepted. Defaults apply only to the kinds that support them. See the [Sequences Guide](./sequences) for timing and matching, and the [App Hotkeys Guide](./app-hotkeys) to declare hotkeys up front and let users customize them.
+
## Logical keys and physical positions
Use a logical binding when the shortcut should follow the character on the active layout. Use a physical binding when it should follow a keyboard position:
@@ -265,7 +277,7 @@ Group is descriptive metadata, not an execution scope. A shortcuts panel can gro
## Introspecting registrations
-Use the `getHotkeyRegistrations` function to get a live view of all hotkey and sequence registrations. This is useful for building shortcut palettes, help dialogs, or devtools.
+Use the `getHotkeyRegistrations` function to get a live view of every registration, chords and sequences together. It's the building block for shortcut palettes and help dialogs.
```svelte
-
-
Keyboard Shortcuts
-
- {#each registrations.hotkeys as reg (reg.hotkey)}
-
```
-The returned object contains a `hotkeys` array with registration objects including the hotkey string, options (including `meta`), and enabled state, and a `sequences` array containing sequence registrations with the same structure.
+The returned object's reactive `hotkeys` getter holds one array of registration views. Each view has an `id`, the `hotkey`, its `options` (including `meta`), its `target`, and a `triggerCount`. Narrow with `kind`: chord views add `parsedHotkey`; sequence views add `parsedSequence` and `matchedStepCount`, the steps matched so far in the current attempt. Disabled entries stay listed; unmounted registrations disappear. Format any hotkey with `formatForDisplay`, and group entries by `options.meta?.group` when building a help panel.
+
+Registrations only exist while their components are mounted. To list hotkeys from routes that have not rendered, declare them with [app hotkeys](./app-hotkeys).
## The hotkey manager
diff --git a/docs/framework/svelte/guides/key-state-tracking.md b/docs/framework/svelte/guides/key-state-tracking.md
index af575606..f12149be 100644
--- a/docs/framework/svelte/guides/key-state-tracking.md
+++ b/docs/framework/svelte/guides/key-state-tracking.md
@@ -104,6 +104,6 @@ tracker.isKeyHeld('Shift')
const hint = getHotkeyHint(() => binding) // reactive getter: hint.visible
```
-For `Alt+Shift+[KeyK]`, holding Alt, Shift, or both reveals the hint. An extra Control hides it; releasing all modifiers or blurring the window hides it. Nonmodifier keys are ignored. AltGraph does not reveal hints. Pass `{ exact: true }` to require all binding modifiers, or `{ platform: 'mac' }` to resolve Mod explicitly. Supply the same platform used by the registration when overriding detection.
+For `Alt+Shift+[KeyK]`, holding Alt, Shift, or both reveals the hint. An extra Control hides it; releasing all modifiers or blurring the window hides it. Nonmodifier keys are ignored. AltGraph does not reveal hints. Pass `{ exact: true }` to require all binding modifiers, or `{ platform: 'mac' }` to resolve Mod explicitly. Supply the same platform used by the registration when overriding detection. A sequence reveals its hint from its first step, and an app hotkey uses its effective hotkey (no hint while unbound).
Combine the boolean with the action's enabled state. The helper does not register a shortcut or determine whether its target is focused. The core equivalent is `matchesHeldModifiers(binding, heldKeys, options)`.
diff --git a/docs/framework/svelte/guides/sequence-recording.md b/docs/framework/svelte/guides/sequence-recording.md
deleted file mode 100644
index 14eab8c5..00000000
--- a/docs/framework/svelte/guides/sequence-recording.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-title: Sequence Recording Guide
-id: sequence-recording
----
-
-Use `createHotkeySequenceRecorder` to capture a series of shortcut chords. By default, each step records its physical code: pressing G twice produces `['[KeyG]', '[KeyG]']`. Set `recordBy: 'key'` to follow logical characters instead. Pass the resulting array directly to sequence registration and format each step for display.
-
-TanStack Hotkeys automatically suppresses registered hotkey and sequence callbacks while any recorder is active. You do not need to set `enabled` from `isRecording`. Registrations remain available for conflict detection, and recorded keys stay suppressed through repeats and key release.
-
-## Reactive options
-
-Recorder options support [property getters and functions returning options](./hotkeys.md#property-getters). Updated callbacks, validation, and recording settings apply during an active session without restarting it. Allow the framework to run its effect or watcher before relying on the update.
-
-## Record and display a sequence
-
-This example uses a Save button so plain Enter can be recorded as a step:
-
-```svelte
-
-
-
-
-{#if recorder.isRecording}
-
-
-{/if}
-```
-
-## State and controls
-
-The recorder exposes `isRecording`, `steps`, and `recordedSequence` as reactive getters. `steps` contains the current attempt; `recordedSequence` contains the last committed result. `startRecording()` begins a new session. `commitRecording()` saves a nonempty attempt, while `cancelRecording()` discards it and calls `onCancel`. `stopRecording()` resets recorder state without calling `onRecord` or `onCancel`.
-
-## Options and keyboard behavior
-
-- `recordBy`: `'code'` by default; `'key'` records produced logical characters.
-- `commitKeys`: `'enter'` by default; plain Enter commits a nonempty sequence. `'none'` lets Enter become a step and requires manual or idle commit.
-- `commitOnEnter: false`: also permits Enter as a step when `commitKeys` is `'enter'`.
-- `idleTimeoutMs`: optionally commits after inactivity following a completed step. No timer runs before the first step.
-- `ignoreInputs`: true by default, including shadow-root inputs. Set false to record from editable fields. Escape still cancels from an input.
-
-Escape cancels. Unmodified Backspace/Delete removes the last step; when already empty it stops and calls only `onClear`. Modifier-only presses, automatic repeats, and IME composition do not append steps. Recorded events and their releases do not trigger application shortcuts.
-
-Set provider defaults through `HotkeysProvider` with `defaultOptions.hotkeySequenceRecorder`.
-
-## Validation and conflicts
-
-`validate(sequence, { events, parsedSequence })` runs at commit. Return true to accept, or false/a message to reject. `detectConflicts` checks live bindings and sequence prefixes, including physical/logical overlap established by the recorded events. `onReject` receives feedback; rejected steps remain editable with Backspace.
-
-The shared options and exclusions are described in the [hotkey recording guide](./hotkey-recording.md#validation-and-conflicts). The application owns reset, persistence, and any binding being edited; clearing never calls `onRecord([])`.
diff --git a/docs/framework/svelte/guides/sequences.md b/docs/framework/svelte/guides/sequences.md
index 33c344f5..e5b993a1 100644
--- a/docs/framework/svelte/guides/sequences.md
+++ b/docs/framework/svelte/guides/sequences.md
@@ -3,162 +3,143 @@ title: Sequences Guide
id: sequences
---
-TanStack Hotkeys supports multi-key sequences in Svelte, where keys are pressed one after another rather than simultaneously.
+A sequence is a hotkey made of chords pressed one after another rather than together. Think Vim-style navigation, cheat codes, or multi-step commands. Sequences are ordinary hotkeys: register them with `createHotkey` and `createHotkeys`, list them with `getHotkeyRegistrations`, record them with `createHotkeyRecorder`, and format them with `formatForDisplay`.
-Sequence steps use the same string syntax as single hotkeys. For example, `['[KeyG]', '[KeyG]']` follows a physical position, while `['G', 'G']` follows the logical letter. A sequence can mix forms, such as `['Mod+[KeyK]', 'C']`. Display steps with `sequence.map((step) => formatForDisplay(step)).join(' → ')`.
+Sequence steps use the same syntax as chords. For example, `['[KeyG]', '[KeyG]']` follows a physical position, while `['G', 'G']` follows the logical letter. A sequence can mix forms, such as `['Mod+[KeyK]', 'C']`.
-## Reactive options
+## Basic usage
-Sequence options support the same [property getter patterns](./hotkeys.md#property-getters) as hotkey options, including `enabled`, `timeout`, and `target`. Updates preserve the registration when its sequence, target, and platform stay the same.
-
-## Global sequences
+Pass an array of chords wherever you pass a hotkey:
```svelte
```
+The user must press the steps in order, each within the timeout window. A one-step array such as `['Escape']` is the chord `'Escape'`.
+
## Many sequences at once
-Use `createHotkeySequences` to register several global sequences in one place (including from a reactive getter). For multiple sequences on a focused element, use `createHotkeySequencesAttachment` the same way you would use `createHotkeySequenceAttachment`.
+`createHotkeys` registers chords and sequences together, including dynamic lists:
-```svelte
-
+createHotkeys([
+ { hotkey: ['G', 'G'], callback: () => scrollToTop() },
+ { hotkey: ['D', 'D'], callback: () => deleteLine(), options: { timeout: 500 } },
+ { hotkey: 'Mod+S', callback: () => save() },
+])
```
-## Scoped sequences
+## Sequence options
-Use `createHotkeySequenceAttachment` when a sequence should only be active while a specific element owns focus.
+Sequences accept the same options as chords, except `requireReset`, plus `timeout`.
-```svelte
-
+The maximum time (in milliseconds) allowed between consecutive steps. If the user takes longer than this between any two steps, the sequence resets. Defaults to `1000` (1 second).
-
- Focus here, then press g then g
-
+```ts
+// Fast sequence - user must type quickly
+createHotkey(['D', 'D'], () => deleteLine(), { timeout: 500 })
+
+// Slow sequence - user has more time between keys
+createHotkey(['Shift+Z', 'Shift+Z'], () => forceQuit(), { timeout: 2000 })
```
-## Matching steps
+`timeout` is only accepted when the hotkey is a sequence. Set a default for every sequence with `HotkeysProvider` (or `setHotkeysContext` in a root component's script):
+
+```svelte
+
+
+
+```
-Both `SequenceManager` and `createSequenceMatcher` ignore modifier-only events, IME composition, and automatic keydown repeats. These events neither advance the sequence nor refresh its timeout: holding G does not complete a two-press G sequence. The manager prefers exact matches over weaker logical-key fallbacks while preserving equally strong matches.
+### `enabled` and `meta`
-## Sequence options
+These work exactly as they do for chords. Disabled sequences stay registered and visible in devtools, and `meta` flows to registrations, devtools, and cheat sheets. See the [Hotkeys Guide](./hotkeys).
```ts
-createHotkeySequence(['G', 'G'], callback, {
- timeout: 1000,
- enabled: true,
-})
+createHotkey(['G', 'G'], () => scrollToTop(), () => ({
+ enabled: isVimMode,
+ meta: { name: 'Go to top', description: 'Scroll to the top of the page' },
+}))
```
-### Reactive `enabled`
+## Sequences with modifiers
-When disabled, the sequence stays registered (visible in devtools); only execution is suppressed.
+Each step in a sequence can include modifiers, and consecutive steps can repeat the same modifier:
-```svelte
-
+// Physical R then T positions, both with Shift
+createHotkey(['Shift+[KeyR]', 'Shift+[KeyT]'], () => doNextAction())
```
-## Default options
+Brackets retain physical positions even when the keys produce different letters. While a sequence is in progress, modifier-only keydown events (Shift, Control, Alt, or Meta pressed alone) are ignored. They neither advance the sequence nor reset progress, so a user can tap or hold Shift between `Shift+R` and `Shift+T`.
-```svelte
-
+```ts
+createHotkeys([
+ { hotkey: ['G', 'G'], callback: () => scrollToTop() },
+ { hotkey: ['G', 'Shift+G'], callback: () => scrollToBottom() },
+ { hotkey: ['D', 'D'], callback: () => deleteLine() },
+ { hotkey: ['D', 'W'], callback: () => deleteWord() },
+ { hotkey: ['C', 'I', 'W'], callback: () => changeInnerWord() },
+])
```
-### `meta`
+## Displaying sequences
-Sequences support the same `meta` option as hotkeys, so you can attach a `name` and `description` for use in shortcut palettes and devtools.
+`formatForDisplay` formats each step and joins them with `sequenceSeparator`, a space by default:
```ts
-createHotkeySequence(['G', 'G'], () => scrollToTop(), {
- meta: { name: 'Go to Top', description: 'Scroll to the top of the page' },
-})
+formatForDisplay(['Mod+K', 'Mod+C'], { platform: 'mac' }) // '⌘ K ⌘ C'
+formatForDisplay(['G', 'G'], { sequenceSeparator: ' then ' }) // 'G then G'
```
-See the [Hotkeys Guide](./hotkeys.md#metadata-name--description) for details on declaration merging and introspecting registrations.
-
-## Chained modifier chords
-
-This example follows physical R and T positions. Brackets retain those positions even when the keys produce different letters. Other sequences can continue using logical characters.
+Registration views report each sequence's progress in `matchedStepCount`, so a help panel can show how far the user has typed. See the [Hotkeys Guide](./hotkeys).
-You can use the same modifier on consecutive steps (for example `Shift+R` then `Shift+T`):
-
-```ts
-createHotkeySequence(['Shift+[KeyR]', 'Shift+[KeyT]'], () => doNextAction())
-```
+## How sequences work
-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.
+The `HotkeyManager` tracks progress for every sequence registration. When a key is pressed:
-## Common patterns
+1. It checks whether the key matches the next expected step of each sequence
+2. If it matches, that sequence advances
+3. If the timeout expires between steps, the sequence resets
+4. When all steps are completed, the callback fires
-### Vim-style navigation
+Modifier-only events, IME composition, and automatic keydown repeats neither advance a sequence nor refresh its timeout: holding G does not complete a two-press G sequence. Exact matches take priority over weaker logical-key fallbacks.
-```ts
-createHotkeySequence(['G', 'G'], () => scrollToTop())
-createHotkeySequence(['G', 'Shift+G'], () => scrollToBottom())
-createHotkeySequence(['D', 'D'], () => deleteLine())
-createHotkeySequence(['D', 'W'], () => deleteWord())
-createHotkeySequence(['C', 'I', 'W'], () => changeInnerWord())
-```
+Multiple sequences can share a prefix, such as `['D', 'D']`, `['D', 'W']`, and `['D', 'I', 'W']`. Progress is tracked for each sequence independently, so after pressing `D` the manager waits for the next key to determine which sequence completes.
-### Konami Code
+### Conflicting registrations
-```ts
-createHotkeySequence(
- ['ArrowUp', 'ArrowUp', 'ArrowDown', 'ArrowDown', 'B', 'A'],
- () => enableEasterEgg(),
- { timeout: 2000 },
-)
-```
+For the same target, duplicate detection compares resolved steps: modifier aliases, modifier order, and logical key casing do not create separate hotkeys. Physical and logical identities remain distinct, and a shared prefix alone is not a duplicate registration. Recorder conflict detection and app hotkey conflicts are stricter: there, a sequence also conflicts with a chord equal to its first step and with any sequence it starts.
-## Under the hood
+## Standalone matching
-`createHotkeySequence` uses the singleton `SequenceManager`. You can also access it directly:
+For sequence matching without the singleton manager, use `createSequenceMatcher`:
```ts
-import {
- createSequenceMatcher,
- getSequenceManager,
-} from '@tanstack/svelte-hotkeys'
+import { createSequenceMatcher } from '@tanstack/svelte-hotkeys'
-const manager = getSequenceManager()
const matcher = createSequenceMatcher(['G', 'G'], { timeout: 1000 })
-```
-
-### Conflicting registrations
-For the same target, duplicate detection compares resolved steps: modifier aliases, modifier order, and logical key casing do not create separate bindings. `conflictBehavior` applies to equivalent sequences without rewriting their stored strings. Physical and logical identities remain distinct, and a shared prefix alone is not a duplicate registration. Recorder conflict detection also checks prefixes and observed physical/logical overlap.
+document.addEventListener('keydown', (e) => {
+ if (matcher.match(e)) {
+ console.log('Sequence completed!')
+ }
+ console.log('Progress:', matcher.getProgress()) // e.g., 1
+})
+```
diff --git a/docs/framework/svelte/quick-start.md b/docs/framework/svelte/quick-start.md
index 2ef2c748..066280a9 100644
--- a/docs/framework/svelte/quick-start.md
+++ b/docs/framework/svelte/quick-start.md
@@ -79,9 +79,10 @@ The `Mod` modifier automatically resolves to `Meta` (Command) on macOS and `Cont
```svelte
@@ -155,18 +156,21 @@ Use `setHotkeysContext` when you want defaults for a subtree. This is an advance
import { setHotkeysContext } from '@tanstack/svelte-hotkeys'
setHotkeysContext({
- hotkey: { preventDefault: true },
- hotkeySequence: { timeout: 1500 },
+ defaultOptions: { hotkey: { preventDefault: true, timeout: 1500 } },
})
```
+## Declaring app hotkeys
+
+To list every hotkey in a cheat sheet, including hotkeys whose components haven't mounted, and to let users customize them, declare them once with `defineAppHotkeys` and provide them with `HotkeysProvider` or `setHotkeysContext`. See the [App Hotkeys Guide](./guides/app-hotkeys).
+
## Next steps
- [Hotkeys Guide](./guides/hotkeys)
- [Sequences Guide](./guides/sequences)
- [Hotkey Recording Guide](./guides/hotkey-recording)
-- [Sequence Recording Guide](./guides/sequence-recording)
+- [App Hotkeys Guide](./guides/app-hotkeys)
- [Key State Tracking Guide](./guides/key-state-tracking)
- [Formatting & Display Guide](./guides/formatting-display)
diff --git a/docs/framework/svelte/reference/functions/createHotkey.md b/docs/framework/svelte/reference/functions/createHotkey.md
index 025eba12..aa155b36 100644
--- a/docs/framework/svelte/reference/functions/createHotkey.md
+++ b/docs/framework/svelte/reference/functions/createHotkey.md
@@ -3,43 +3,112 @@ id: createHotkey
title: createHotkey
---
+## Call Signature
+
```ts
-function createHotkey(
+function createHotkey(
hotkey,
callback,
options?): void;
```
-Defined in: [packages/svelte-hotkeys/src/createHotkey.svelte.ts:56](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkey.svelte.ts#L56)
+Defined in: [packages/svelte-hotkeys/src/createHotkey.svelte.ts:62](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkey.svelte.ts#L62)
+
+Svelte function for registering a hotkey on the document: a chord such as
+`'Mod+S'`, a sequence such as `['G', 'G']`, or an app hotkey from
+`defineAppHotkeys`. Pass getters for reactive values. Use
+`createHotkeyAttachment` for element-scoped hotkeys.
+
+Chords accept `requireReset`; sequences accept `timeout`. A one-step
+sequence registers as its chord. An app hotkey uses its effective hotkey
+from `HotkeysProvider` (including the user's custom hotkey) and its
+declared meta and options, and registers nothing while unbound.
+
+### Type Parameters
+
+#### T
-Register a global hotkey for the current component.
+`T` *extends* `AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>
-## Parameters
+### Parameters
-### hotkey
+#### hotkey
-`MaybeGetter`\<`RegisterableHotkey`\>
+`MaybeGetter`\<`T`\>
-### callback
+#### callback
`HotkeyCallback`
-### options?
+#### options?
-`MaybeGetter`\<[`CreateHotkeyOptions`](../interfaces/CreateHotkeyOptions.md)\> = `{}`
+`MaybeGetter`\<[`CreateAppHotkeyOptions`](../type-aliases/CreateAppHotkeyOptions.md)\<`T`\>\>
-## Returns
+### Returns
`void`
-## Example
+### Example
```svelte
+```
+
+## Call Signature
+
+```ts
+function createHotkey(
+ hotkey,
+ callback,
+ options?): void;
+```
+
+Defined in: [packages/svelte-hotkeys/src/createHotkey.svelte.ts:67](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkey.svelte.ts#L67)
+
+Svelte function for registering a hotkey on the document: a chord such as
+`'Mod+S'`, a sequence such as `['G', 'G']`, or an app hotkey from
+`defineAppHotkeys`. Pass getters for reactive values. Use
+`createHotkeyAttachment` for element-scoped hotkeys.
+
+Chords accept `requireReset`; sequences accept `timeout`. A one-step
+sequence registers as its chord. An app hotkey uses its effective hotkey
+from `HotkeysProvider` (including the user's custom hotkey) and its
+declared meta and options, and registers nothing while unbound.
- createHotkey('Mod+S', () => {
- console.log('Mod+S pressed')
- })
+### Type Parameters
+
+#### T
+
+`T` *extends* `RegisterableHotkey`
+
+### Parameters
+
+#### hotkey
+
+`MaybeGetter`\<`T`\>
+
+#### callback
+
+`HotkeyCallback`
+
+#### options?
+
+`MaybeGetter`\<`AdapterOptionsFor`\<`T`, [`CreateHotkeyTarget`](../type-aliases/CreateHotkeyTarget.md)\>\>
+
+### Returns
+
+`void`
+
+### Example
+
+```svelte
+
```
diff --git a/docs/framework/svelte/reference/functions/createHotkeyAttachment.md b/docs/framework/svelte/reference/functions/createHotkeyAttachment.md
index fa0775cf..1cc82d33 100644
--- a/docs/framework/svelte/reference/functions/createHotkeyAttachment.md
+++ b/docs/framework/svelte/reference/functions/createHotkeyAttachment.md
@@ -3,49 +3,98 @@ id: createHotkeyAttachment
title: createHotkeyAttachment
---
+## Call Signature
+
```ts
-function createHotkeyAttachment(
+function createHotkeyAttachment(
hotkey,
callback,
options?): Attachment;
```
-Defined in: [packages/svelte-hotkeys/src/createHotkey.svelte.ts:130](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkey.svelte.ts#L130)
+Defined in: [packages/svelte-hotkeys/src/createHotkey.svelte.ts:93](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkey.svelte.ts#L93)
+
+Create an attachment for an element-scoped hotkey: a chord, a sequence, or
+an app hotkey that listens on the attached element.
+
+### Type Parameters
+
+#### T
-Create an attachment for element-scoped hotkeys.
+`T` *extends* `AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>
-## Parameters
+### Parameters
-### hotkey
+#### hotkey
-`MaybeGetter`\<`RegisterableHotkey`\>
+`MaybeGetter`\<`T`\>
-### callback
+#### callback
`HotkeyCallback`
-### options?
+#### options?
-`MaybeGetter`\<[`CreateHotkeyOptions`](../interfaces/CreateHotkeyOptions.md)\> = `{}`
+`MaybeGetter`\<[`CreateAppHotkeyOptions`](../type-aliases/CreateAppHotkeyOptions.md)\<`T`\>\>
-## Returns
+### Returns
`Attachment`\<`HTMLElement`\>
-## Example
+### Example
```svelte
+
+
Editor content
+```
+
+## Call Signature
+
+```ts
+function createHotkeyAttachment(
+ hotkey,
+ callback,
+options?): Attachment;
+```
+
+Defined in: [packages/svelte-hotkeys/src/createHotkey.svelte.ts:98](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkey.svelte.ts#L98)
+
+Create an attachment for an element-scoped hotkey: a chord, a sequence, or
+an app hotkey that listens on the attached element.
- let count = $state(0)
- const saveHotkey = createHotkeyAttachment('Mod+S', () => {
- count++
- })
+### Type Parameters
+#### T
+
+`T` *extends* `RegisterableHotkey`
+
+### Parameters
+
+#### hotkey
+
+`MaybeGetter`\<`T`\>
+
+#### callback
+
+`HotkeyCallback`
+
+#### options?
+
+`MaybeGetter`\<`AdapterOptionsFor`\<`T`, [`CreateHotkeyTarget`](../type-aliases/CreateHotkeyTarget.md)\>\>
+
+### Returns
+
+`Attachment`\<`HTMLElement`\>
+
+### Example
+
+```svelte
+
-
- Count: {count}
-
+
Editor content
```
diff --git a/docs/framework/svelte/reference/functions/createHotkeyRecorder.md b/docs/framework/svelte/reference/functions/createHotkeyRecorder.md
index 265d7e7a..70c2fa31 100644
--- a/docs/framework/svelte/reference/functions/createHotkeyRecorder.md
+++ b/docs/framework/svelte/reference/functions/createHotkeyRecorder.md
@@ -3,18 +3,192 @@ id: createHotkeyRecorder
title: createHotkeyRecorder
---
+## Call Signature
+
+```ts
+function createHotkeyRecorder(options): SvelteHotkeyRecorder;
+```
+
+Defined in: [packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts:102](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts#L102)
+
+Svelte function for recording keyboard shortcuts. Options may be a getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+`HotkeyChordRecorderOptions`
+
+### Returns
+
+[`SvelteHotkeyRecorder`](../interfaces/SvelteHotkeyRecorder.md)\<`HotkeyChord`\>
+
+### Example
+
+```svelte
+
+
+
+```
+
+## Call Signature
+
+```ts
+function createHotkeyRecorder(options): SvelteHotkeyRecorder;
+```
+
+Defined in: [packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts:105](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts#L105)
+
+Svelte function for recording keyboard shortcuts. Options may be a getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+`HotkeySequenceRecorderOptions`
+
+### Returns
+
+[`SvelteHotkeyRecorder`](../interfaces/SvelteHotkeyRecorder.md)
+
+### Example
+
+```svelte
+
+
+
+```
+
+## Call Signature
+
```ts
function createHotkeyRecorder(options): SvelteHotkeyRecorder;
```
-Defined in: [packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts:101](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts#L101)
+Defined in: [packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts:110](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts#L110)
+
+Svelte function for recording keyboard shortcuts. Options may be a getter.
-## Parameters
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
-### options
+### Parameters
-`MaybeGetter`\<`HotkeyRecorderOptions`\>
+#### options
-## Returns
+() => `HotkeySequenceRecorderOptions`
+
+### Returns
[`SvelteHotkeyRecorder`](../interfaces/SvelteHotkeyRecorder.md)
+
+### Example
+
+```svelte
+
+
+
+```
+
+## Call Signature
+
+```ts
+function createHotkeyRecorder(options): SvelteHotkeyRecorder;
+```
+
+Defined in: [packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts:113](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts#L113)
+
+Svelte function for recording keyboard shortcuts. Options may be a getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+() => `HotkeyChordRecorderOptions`
+
+### Returns
+
+[`SvelteHotkeyRecorder`](../interfaces/SvelteHotkeyRecorder.md)\<`HotkeyChord`\>
+
+### Example
+
+```svelte
+
+
+
+```
+
+## Call Signature
+
+```ts
+function createHotkeyRecorder(options): SvelteHotkeyRecorder;
+```
+
+Defined in: [packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts:116](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeyRecorder.svelte.ts#L116)
+
+Svelte function for recording keyboard shortcuts. Options may be a getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+() => `HotkeyRecorderOptions`
+
+### Returns
+
+[`SvelteHotkeyRecorder`](../interfaces/SvelteHotkeyRecorder.md)
+
+### Example
+
+```svelte
+
+
+
+```
diff --git a/docs/framework/svelte/reference/functions/createHotkeySequence.md b/docs/framework/svelte/reference/functions/createHotkeySequence.md
deleted file mode 100644
index 7cca3164..00000000
--- a/docs/framework/svelte/reference/functions/createHotkeySequence.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-id: createHotkeySequence
-title: createHotkeySequence
----
-
-```ts
-function createHotkeySequence(
- sequence,
- callback,
- options?): void;
-```
-
-Defined in: [packages/svelte-hotkeys/src/createHotkeySequence.svelte.ts:72](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeySequence.svelte.ts#L72)
-
-Register a global keyboard shortcut sequence for the current component.
-
-Each step may include modifiers. You can chain the same modifier across
-steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
-Control, Alt, or Meta pressed alone) are ignored while matching—they do not
-advance the sequence or reset progress.
-
-## Parameters
-
-### sequence
-
-`MaybeGetter`\<`HotkeySequence`\>
-
-### callback
-
-`HotkeyCallback`
-
-### options?
-
-`MaybeGetter`\<[`CreateHotkeySequenceOptions`](../interfaces/CreateHotkeySequenceOptions.md)\> = `{}`
-
-## Returns
-
-`void`
-
-## Example
-
-```svelte
-
-
-
-```
diff --git a/docs/framework/svelte/reference/functions/createHotkeys.md b/docs/framework/svelte/reference/functions/createHotkeys.md
index 2fef9b8c..5d309363 100644
--- a/docs/framework/svelte/reference/functions/createHotkeys.md
+++ b/docs/framework/svelte/reference/functions/createHotkeys.md
@@ -7,19 +7,25 @@ title: createHotkeys
function createHotkeys(hotkeys, commonOptions?): void;
```
-Defined in: [packages/svelte-hotkeys/src/createHotkeys.svelte.ts:65](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeys.svelte.ts#L65)
+Defined in: [packages/svelte-hotkeys/src/createHotkeys.svelte.ts:128](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeys.svelte.ts#L128)
-Register multiple global hotkeys for the current component.
+Svelte function for registering several hotkeys at once on the document:
+chords, sequences, and app hotkeys. Pass getters for reactive values. Use
+`createHotkeysAttachment` for element-scoped hotkeys.
+
+Options merge in this order: provider defaults, app hotkey declaration,
+commonOptions, per-hotkey options. Each option applies only to the kinds
+that support it. Unbound app hotkeys and empty sequences register nothing.
## Parameters
### hotkeys
-`MaybeGetter`\<[`CreateHotkeyDefinition`](../interfaces/CreateHotkeyDefinition.md)[]\>
+`MaybeGetter`\
### commonOptions?
-`MaybeGetter`\<[`CreateHotkeyOptions`](../interfaces/CreateHotkeyOptions.md)\> = `{}`
+`MaybeGetter`\<[`CreateHotkeyCommonOptions`](../type-aliases/CreateHotkeyCommonOptions.md)\> = `{}`
## Returns
@@ -29,12 +35,9 @@ Register multiple global hotkeys for the current component.
```svelte
```
diff --git a/docs/framework/svelte/reference/functions/createHotkeysAttachment.md b/docs/framework/svelte/reference/functions/createHotkeysAttachment.md
index b90e5943..9be741b2 100644
--- a/docs/framework/svelte/reference/functions/createHotkeysAttachment.md
+++ b/docs/framework/svelte/reference/functions/createHotkeysAttachment.md
@@ -7,19 +7,20 @@ title: createHotkeysAttachment
function createHotkeysAttachment(hotkeys, commonOptions?): Attachment;
```
-Defined in: [packages/svelte-hotkeys/src/createHotkeys.svelte.ts:188](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeys.svelte.ts#L188)
+Defined in: [packages/svelte-hotkeys/src/createHotkeys.svelte.ts:152](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/createHotkeys.svelte.ts#L152)
-Create an attachment for element-scoped multi-hotkey registration.
+Create an attachment for element-scoped hotkeys: chords, sequences, and app
+hotkeys listen on the attached element.
## Parameters
### hotkeys
-`MaybeGetter`\<[`CreateHotkeyDefinition`](../interfaces/CreateHotkeyDefinition.md)[]\>
+`MaybeGetter`\
### commonOptions?
-`MaybeGetter`\<[`CreateHotkeyOptions`](../interfaces/CreateHotkeyOptions.md)\> = `{}`
+`MaybeGetter`\<[`CreateHotkeyCommonOptions`](../type-aliases/CreateHotkeyCommonOptions.md)\> = `{}`
## Returns
@@ -29,15 +30,11 @@ Create an attachment for element-scoped multi-hotkey registration.
```svelte
-
- Editor content
-
+
Editor content
```
diff --git a/docs/framework/svelte/reference/functions/getAppHotkeyList.md b/docs/framework/svelte/reference/functions/getAppHotkeyList.md
new file mode 100644
index 00000000..223dfb0e
--- /dev/null
+++ b/docs/framework/svelte/reference/functions/getAppHotkeyList.md
@@ -0,0 +1,18 @@
+---
+id: getAppHotkeyList
+title: getAppHotkeyList
+---
+
+```ts
+function getAppHotkeyList(): SvelteAppHotkeyList;
+```
+
+Defined in: [packages/svelte-hotkeys/src/getAppHotkeys.svelte.ts:63](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getAppHotkeys.svelte.ts#L63)
+
+Lists every app hotkey with its live status, for cheat sheets and settings
+screens. App hotkeys whose components have not mounted are `'inactive'`;
+those without a hotkey are `'unbound'`.
+
+## Returns
+
+[`SvelteAppHotkeyList`](../interfaces/SvelteAppHotkeyList.md)
diff --git a/docs/framework/svelte/reference/functions/getAppHotkeys.md b/docs/framework/svelte/reference/functions/getAppHotkeys.md
new file mode 100644
index 00000000..c2f7cfc2
--- /dev/null
+++ b/docs/framework/svelte/reference/functions/getAppHotkeys.md
@@ -0,0 +1,26 @@
+---
+id: getAppHotkeys
+title: getAppHotkeys
+---
+
+```ts
+function getAppHotkeys(): SvelteAppHotkeys;
+```
+
+Defined in: [packages/svelte-hotkeys/src/getAppHotkeys.svelte.ts:41](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getAppHotkeys.svelte.ts#L41)
+
+Returns reactive access to the effective app hotkeys from `HotkeysProvider`,
+typed by `Register`.
+
+## Returns
+
+[`SvelteAppHotkeys`](../interfaces/SvelteAppHotkeys.md)
+
+## Example
+
+```svelte
+
+```
diff --git a/docs/framework/svelte/reference/functions/getCustomHotkeys.md b/docs/framework/svelte/reference/functions/getCustomHotkeys.md
new file mode 100644
index 00000000..7a0ea8cc
--- /dev/null
+++ b/docs/framework/svelte/reference/functions/getCustomHotkeys.md
@@ -0,0 +1,18 @@
+---
+id: getCustomHotkeys
+title: getCustomHotkeys
+---
+
+```ts
+function getCustomHotkeys(): SvelteCustomHotkeys;
+```
+
+Defined in: [packages/svelte-hotkeys/src/getAppHotkeys.svelte.ts:101](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getAppHotkeys.svelte.ts#L101)
+
+Reads and changes the user's custom hotkeys. Changes apply to every
+registered app hotkey immediately and are passed to the provider's
+`onCustomHotkeysChange`, ready to save.
+
+## Returns
+
+[`SvelteCustomHotkeys`](../interfaces/SvelteCustomHotkeys.md)
diff --git a/docs/framework/svelte/reference/functions/getDefaultHotkeysOptions.md b/docs/framework/svelte/reference/functions/getDefaultHotkeysOptions.md
index 6faf5355..f09464c0 100644
--- a/docs/framework/svelte/reference/functions/getDefaultHotkeysOptions.md
+++ b/docs/framework/svelte/reference/functions/getDefaultHotkeysOptions.md
@@ -7,7 +7,7 @@ title: getDefaultHotkeysOptions
function getDefaultHotkeysOptions(): HotkeysProviderOptions;
```
-Defined in: [packages/svelte-hotkeys/src/HotkeysCtx.ts:59](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/HotkeysCtx.ts#L59)
+Defined in: [packages/svelte-hotkeys/src/HotkeysCtx.ts:110](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/HotkeysCtx.ts#L110)
## Returns
diff --git a/docs/framework/svelte/reference/functions/getHotkeyHint.md b/docs/framework/svelte/reference/functions/getHotkeyHint.md
index 835014ac..99f9eda9 100644
--- a/docs/framework/svelte/reference/functions/getHotkeyHint.md
+++ b/docs/framework/svelte/reference/functions/getHotkeyHint.md
@@ -7,19 +7,21 @@ title: getHotkeyHint
function getHotkeyHint(hotkey, options?): SvelteHotkeyHint;
```
-Defined in: [packages/svelte-hotkeys/src/getHotkeyHint.svelte.ts:18](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getHotkeyHint.svelte.ts#L18)
+Defined in: [packages/svelte-hotkeys/src/getHotkeyHint.svelte.ts:28](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getHotkeyHint.svelte.ts#L28)
-Returns an object with a reactive `visible` getter indicating whether held modifiers reveal this shortcut.
-Pass getters to track changing bindings and options.
-Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
-every modifier. Combine with the action's enabled state before showing a badge.
-This helper does not register a shortcut or check whether its target is focused.
+Returns an object with a reactive `visible` getter indicating whether held
+modifiers reveal this shortcut. Pass getters to track changing hotkeys and
+options. A sequence reveals its hint from its first step, and an app hotkey
+uses its effective hotkey (false while unbound). This helper does not
+register a shortcut or check whether its target is focused.
## Parameters
### hotkey
-`MaybeGetter`\<`RegisterableHotkey`\>
+`MaybeGetter`\<
+ \| `RegisterableHotkey`
+ \| `AppHotkey`\<`string`, HotkeyChord \| HotkeySequence \| null\>\>
### options?
diff --git a/docs/framework/svelte/reference/functions/getHotkeyRegistrations.md b/docs/framework/svelte/reference/functions/getHotkeyRegistrations.md
index 892d2a43..6879ded4 100644
--- a/docs/framework/svelte/reference/functions/getHotkeyRegistrations.md
+++ b/docs/framework/svelte/reference/functions/getHotkeyRegistrations.md
@@ -7,28 +7,25 @@ title: getHotkeyRegistrations
function getHotkeyRegistrations(): SvelteHotkeyRegistrations;
```
-Defined in: [packages/svelte-hotkeys/src/getHotkeyRegistrations.svelte.ts:58](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getHotkeyRegistrations.svelte.ts#L58)
+Defined in: [packages/svelte-hotkeys/src/getHotkeyRegistrations.svelte.ts:39](https://github.com/TanStack/hotkeys/blob/main/packages/svelte-hotkeys/src/getHotkeyRegistrations.svelte.ts#L39)
-Svelte function that returns reactive access to all hotkey and sequence
-registrations from the singleton managers.
+Svelte function that returns reactive access to every hotkey registration,
+chords and sequences, from the singleton HotkeyManager.
-This is a standalone function that does NOT require the HotkeysProvider.
+This function does NOT require the HotkeysProvider.
## Returns
[`SvelteHotkeyRegistrations`](../interfaces/SvelteHotkeyRegistrations.md)
-Object with reactive `hotkeys` and `sequences` properties
-
## Example
```svelte
-
-{#each registrations.hotkeys as reg}
-
+
+```
+
+An app hotkey registered by many components, such as one per list row, appears once. Its `registrations` array holds each live registration. Devtools also list declared app hotkeys that are not registered.
+
+## Customize and persist hotkeys
+
+TanStack Hotkeys does not store anything. Pass the user's saved custom hotkeys in and save them when they change:
+
+```vue
+
+
+
+
+
+
+
+```
+
+The provider emits `customHotkeysChange` with the complete custom hotkeys after every change. With `provideHotkeysContext`, pass `customHotkeys` and `onCustomHotkeysChange` in its options instead.
+
+- `customHotkeys` holds only the hotkeys that differ from the declared defaults, keyed by id. `null` means the user unbound that hotkey. Saving differences means users who never changed a hotkey get new defaults when you change them.
+- `customHotkeys` is read once; afterwards the shared store owns the state. Saved data can outlive the code that wrote it, so unknown ids and invalid hotkeys are ignored with a warning.
+- `onCustomHotkeysChange` receives the complete custom hotkeys after every change, ready to save. Storage can be anything: local storage, a server, or a user profile.
+
+Recorded hotkeys use `Mod` rather than platform-specific modifiers, so a hotkey saved on one platform works on others.
+
+### Change hotkeys
+
+`useCustomHotkeys` reads and changes the user's custom hotkeys:
+
+```vue
+
+
+
+
+
+```
+
+| Member | Description |
+| --- | --- |
+| `customHotkeys.value` | The hotkeys that differ from the defaults |
+| `setCustomHotkey(id, hotkey)` | Sets a hotkey, or unbinds with `null`. Returns conflicting app hotkeys; when there are any, nothing changes. |
+| `findConflicts(id, hotkey)` | App hotkeys that would collide if `id` used `hotkey` |
+| `resetCustomHotkey(id)` | Restores one default |
+| `resetCustomHotkeys()` | Restores every default |
+
+Two app hotkeys conflict when their contexts match or either has no `context`, and their hotkeys collide: equal chords, or one sequence starts with the other, including a sequence whose first step equals a chord. Conflicts are checked across every declaration, whether or not it is registered.
+
+Each app hotkey's `defaultHotkey` holds its declared default, and each cheat sheet item's `isCustom` reports whether the effective hotkey differs from it.
diff --git a/docs/framework/vue/guides/formatting-display.md b/docs/framework/vue/guides/formatting-display.md
index 46c42dfc..f23ab316 100644
--- a/docs/framework/vue/guides/formatting-display.md
+++ b/docs/framework/vue/guides/formatting-display.md
@@ -3,7 +3,7 @@ title: Formatting & Display Guide
id: formatting-display
---
-Use `formatForDisplay` whenever a binding appears in a menu, button, hint, or shortcut settings panel. It accepts logical strings, bracketed physical strings, raw objects, and parsed bindings. Store the original binding and format it at render time: the display label is not a registration string.
+Use `formatForDisplay` whenever a hotkey appears in a menu, button, hint, cheat sheet, or shortcut settings panel. It accepts logical strings, bracketed physical strings, raw objects, parsed bindings, and sequences. Store the original binding and format it at render time: the display label is not a registration string.
## Format a binding
@@ -32,16 +32,18 @@ const parts = formatForDisplay(binding, { platform: 'mac', parts: true })
With `parts` omitted or false, the result is a string. A runtime boolean returns `string | string[]`. Parts preserve literal plus keys and ignore `separatorToken`.
-Sequences are arrays of bindings. Format their steps individually:
+## Format sequences
-```ts
-import type { HotkeySequence } from '@tanstack/vue-hotkeys'
+Pass a sequence to format each step and join the steps with `sequenceSeparator`, a space by default:
-const sequence: HotkeySequence = ['Mod+[KeyK]', 'C']
-const label = sequence.map((step) => formatForDisplay(step)).join(' → ')
+```ts
+formatForDisplay(['Mod+[KeyK]', 'C'], { platform: 'mac' }) // '⌘ K C'
+formatForDisplay(['G', 'G'], { sequenceSeparator: ' → ' }) // 'G → G'
+formatForDisplay(['Mod+[KeyK]', 'C'], { platform: 'mac', parts: true })
+// [['⌘', 'K'], ['C']] — one array of keycaps per step
```
-`formatHotkeySequence` only joins stored strings with spaces. It intentionally retains brackets and code names, so use the code above for user-facing labels.
+With `parts: true`, a sequence returns one array per step, so you can render each step as a group of keycaps.
## Choose symbols and separators
@@ -63,7 +65,7 @@ formatForDisplay('Control++', {
}) // 'Ctrl · +'
```
-An empty separator joins labels directly. `undefined` or `null` uses the platform default. `formatWithLabels(binding, options)` is the shorthand for `formatForDisplay` with `useSymbols: false`.
+An empty separator joins labels directly. `undefined` or `null` uses the platform default. `separatorToken` applies within a chord; `sequenceSeparator` applies between steps.
## Supply layout labels
@@ -88,6 +90,10 @@ formatForDisplay('Mod+[KeyQ]', {
The precedence is `keyLabels`, then a layout entry, then the fallback label. Layout entries receive normal letter casing and key symbols; missing or empty entries fall back. Explicit labels are final. All of these options affect display only.
+## Compare hotkeys
+
+`areHotkeysEqual(a, b)` compares chords or sequences after resolving modifiers, so `Mod+S` equals `Meta+S` on macOS. Sequences compare step by step. `isHotkeySequence` narrows a `Hotkey` to a sequence, and `simplifyHotkey` turns a one-step sequence into its chord.
+
## Parse and store bindings
`parseHotkey` returns either a logical `key` or a physical `code`, plus resolved modifier flags. Narrow the union before inspecting the identity:
@@ -105,6 +111,6 @@ formatForDisplay(stored, { platform: 'windows' }) // 'Ctrl+S'
Parsed modifiers are already resolved. To display a portable `Mod` binding on another platform, serialize with the original platform first, as above. `normalizeRegisterableHotkey` accepts strings or raw objects and preserves the logical/physical distinction. Do not store display labels or put a bracketed code in a logical `key` field.
-Use `validateHotkey` when accepting strings from an external source. It returns `valid`, `errors`, and `warnings`; it does not guarantee that a browser or operating system will deliver the shortcut. Recorder validation and live conflict checks are covered in the [recording guide](./hotkey-recording.md#validation-and-conflicts).
+Use `validateHotkey` when accepting a chord or sequence from an external source. It returns `valid`, `errors`, and `warnings`, and names the failing step of a sequence; it does not guarantee that a browser or operating system will deliver the shortcut. Recorder validation and live conflict checks are covered in the [recording guide](./hotkey-recording.md#validation-and-conflicts).
Try these options together in the [vanilla formatter playground](../../../framework/vanilla/examples/formatForDisplay).
diff --git a/docs/framework/vue/guides/hotkey-recording.md b/docs/framework/vue/guides/hotkey-recording.md
index 62a8b7e5..2493ab55 100644
--- a/docs/framework/vue/guides/hotkey-recording.md
+++ b/docs/framework/vue/guides/hotkey-recording.md
@@ -3,119 +3,138 @@ title: Hotkey Recording Guide
id: hotkey-recording
---
-TanStack Hotkeys provides the `useHotkeyRecorder` composable for building shortcut customization UIs in Vue.
+`useHotkeyRecorder` is for building keyboard shortcut customization UIs. Users record their own shortcuts by pressing the key combination they want, the same way system preferences or IDE shortcut editors work. By default it records one chord; set `maxSteps` to let users record a [sequence](./sequences) too.
Recorders default to physical codes: recording a shortcut stores a string such as `Mod+[KeyS]`. Pass it directly to your hotkey registration and use `formatForDisplay` for the label. Set `recordBy: 'key'` when you intentionally want the produced character instead.
-TanStack Hotkeys automatically suppresses registered hotkey and sequence callbacks while any recorder is active. You do not need to set `enabled` from `isRecording`. Registrations remain available for conflict detection, and recorded keys stay suppressed through repeats and key release.
-
-## Reactive options
-
-Recorder options support [property getters and functions returning options](./hotkeys.md#property-getters). Updated callbacks, validation, and recording settings apply during an active session without restarting it. Allow the framework to run its effect or watcher before relying on the update.
+TanStack Hotkeys automatically suppresses registered hotkey callbacks while any recorder is active. You do not need to disable hotkeys while recording. Registrations remain available for conflict detection, and recorded keys stay suppressed through repeats and key release.
## Basic usage
```vue
-
-
-
-
+
```
-## Return value
+## Recorder state and actions
+
+| Member | Description |
+| --- | --- |
+| `isRecording` | Whether the recorder is currently listening for key presses |
+| `steps` | Chords captured so far in a multi-step recording |
+| `recordedHotkey` | The last recorded hotkey, or `null` if nothing recorded |
+| `startRecording()` | Start listening for key presses |
+| `stopRecording()` | Stop listening without calling `onRecord` or `onCancel` |
+| `cancelRecording()` | Stop listening and call `onCancel` |
+| `commitRecording()` | Commit the current `steps` now (multi-step recordings) |
-- `isRecording`: reactive ref-like value indicating whether recording is active
-- `recordedHotkey`: reactive ref-like value with the most recently recorded hotkey
-- `startRecording()`: start listening for key presses
-- `stopRecording()`: stop listening and reset recorder state without calling `onRecord`
-- `cancelRecording()`: stop listening and discard the in-progress recording
+State members are readonly refs. Destructure them at the top level of `
+### `onCancel`
-
-
-
-
-
-```
+Called when recording is cancelled, by pressing Escape or calling `cancelRecording()`.
+
+### `onClear`
+
+Called when the recording is cleared: Backspace or Delete with no modifiers and no recorded steps. Clearing calls only `onClear`; your app decides whether that removes a hotkey or restores a default.
### `ignoreInputs`
-The `HotkeyRecorderOptions` supports an `ignoreInputs` option (defaults to `true`). When `true`, the recorder doesn't 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 an input has focus. Set `ignoreInputs: false` if you want the recorder to capture keys from within input elements.
+Defaults to `true`. The recorder doesn't intercept normal typing in text inputs, textareas, selects, or contentEditable elements; keystrokes pass through to the input as usual. Escape still cancels recording even while an input is focused. Set `ignoreInputs: false` to record from inside input elements.
+
+Options can also be a ref or getter, such as `useHotkeyRecorder(() => ({ maxSteps: 3, recordBy: mode.value, onRecord }))`, so recording policy can follow reactive state.
+
+### Default options
+
+Set defaults for every recorder with `HotkeysProvider` (or `provideHotkeysContext` in a root component's setup). Per-recorder options override them.
+
+```vue
+
+
+
+```
+
+## Recording sequences
+
+Set `maxSteps` above 1 to record up to that many chords. Each chord adds a step, and the recording commits when the user presses Enter, when it reaches `maxSteps`, or after `idleTimeoutMs` without a new step:
```ts
-useHotkeyRecorder({
- ignoreInputs: false, // record even from inside inputs
- onRecord: (hotkey) => console.log(hotkey),
+const recorder = useHotkeyRecorder({
+ maxSteps: 3,
+ onRecord: (hotkey) => console.log('Recorded:', hotkey), // 'Mod+[KeyS]' or ['[KeyG]', '[KeyG]']
})
+
+// Live preview while recording
+const label = computed(() =>
+ recorder.isRecording.value
+ ? formatForDisplay(recorder.steps.value) || 'Press chords, then Enter…'
+ : formatForDisplay(recorder.recordedHotkey.value ?? []),
+)
```
+A one-step recording commits as a chord, so the result can always be passed straight to your hotkey registration. Use `maxSteps: Infinity` for no limit.
+
+| Option | Description |
+| --- | --- |
+| `maxSteps` | Maximum chords to record. Reaching it commits. Default `1`. |
+| `commitKeys` | `'enter'` (default) commits on plain Enter. With `'none'`, plain Enter can be recorded as a step, and only `commitRecording()`, `idleTimeoutMs`, or `maxSteps` commit. |
+| `idleTimeoutMs` | Commit automatically after this many milliseconds without a new step. The timer does not run before the first chord. |
+
+`commitKeys` and `idleTimeoutMs` are only accepted when `maxSteps` is set. With `maxSteps` above 1, `onRecord` and `validate` receive `Hotkey` (a chord or a sequence) instead of a chord.
+
## Recording behavior
-- Modifier-only presses do not complete a recording.
-- Modifier plus key combinations record the full shortcut.
-- Escape cancels recording.
-- Backspace and Delete clear the shortcut.
-- Recorded values are normalized to portable `Mod` format.
+| Key | Behavior |
+| --- | --- |
+| Modifier only (Shift, Ctrl, etc.) | Waits for a non-modifier key; modifier-only presses don't complete a step |
+| Modifier + key (e.g., Ctrl+S) | Records the full combination |
+| Single key (e.g., Escape, F1) | Records the single key |
+| Enter (multi-step, `commitKeys: 'enter'`) | Commits the recorded steps |
+| Escape | Cancels the recording |
+| Backspace / Delete | Removes the last step; with no steps, clears and calls `onClear` |
+
+Repeats and IME composition never add a step. Recorded hotkeys use the portable `Mod` format: Command+S on macOS records `Mod+[KeyS]` rather than `Meta+[KeyS]`, so the primary modifier becomes Control if the hotkey is later used on Windows.
## Validation and conflicts
-Both recorder APIs accept `detectConflicts`, `validate`, and `onReject`. For a single-hotkey recorder, these options can be supplied alongside `onRecord`:
+The recorder accepts `detectConflicts`, `validate`, and `onReject` alongside `onRecord`:
```ts
const options = {
detectConflicts: {
- // Use registration IDs to exclude the binding being edited:
+ // Use registration IDs to exclude the hotkey being edited:
excludeIds: [registrationId],
target: document,
eventType: 'keydown',
@@ -129,8 +148,63 @@ const options = {
}
```
-`validate` returns true to accept, or false/a message to reject. `onReject` receives `reason` (`missing-code`, `alt-graph`, `invalid`, `validation`, or `conflict`), a message, the candidate when available, and conflicting registration views for conflict rejections. Validation runs before commit; rejection never falls back to another key identity.
+`validate(hotkey, context)` returns true to accept, or false/a message to reject. The context holds the last chord's `event` and `parsedHotkey`, plus `events` and `parsedSequence` for every step. `onReject` receives `reason` (`missing-code`, `alt-graph`, `invalid`, `validation`, or `conflict`), a message, the rejected `hotkey` when available, and conflicting registrations for conflict rejections. Validation runs before commit; rejection never falls back to another key identity. A rejected multi-step recording keeps its steps so the user can edit them with Backspace.
+
+`detectConflicts: true` checks enabled live registrations with the intended event type (default keydown) and overlapping targets (default document). Document/nested scopes can conflict; disjoint widgets can reuse a hotkey. The options object also supports `scope: 'all'`, `includeDisabled`, and an `exclude(registration)` predicate. Chords and sequence prefixes are checked: a recorded chord conflicts with a sequence that starts with it, and a recorded sequence conflicts with a registered chord equal to its first step. Source events detect physical/logical overlap on the recorded layout. This is a conservative collision check, not a promise that two callbacks will execute.
+
+For checks outside recording, use `findHotkeyConflicts(hotkey, options)`. Without source `events`, it compares hotkey identity and sequence prefixes; it does not guess equivalence between a logical character and a physical position.
+
+## Building a shortcut settings UI
+
+For an app-wide settings screen, declare the hotkeys with [app hotkeys](./app-hotkeys) and save the recorder's result with `setCustomHotkey`. That keeps cheat sheets, conflicts, and persistence in one place.
+
+For a single component, ordinary state is enough:
+
+```vue
+
+
+
+
+
+```
-`detectConflicts: true` checks enabled live registrations with the intended event type (default keydown) and overlapping targets (default document). Document/nested scopes can conflict; disjoint widgets can reuse a binding. The options object also supports `scope: 'all'`, `includeDisabled`, and an `exclude(registration)` predicate. Both single bindings and sequence prefixes are checked. Source events detect physical/logical overlap on the recorded layout. This is a conservative collision check, not a promise that two callbacks will execute: propagation, input filtering, match priority, external listeners, unmounted routes, and other layouts can affect actual dispatch.
+## Under the hood
-For checks outside recording, use `findHotkeyConflicts(bindingOrSequence, options)`. Without source `events`, it compares binding identity and sequence prefixes; it does not guess equivalence between a logical character and a physical position.
+`useHotkeyRecorder` creates a `HotkeyRecorder` from `@tanstack/hotkeys`, exposes its state as refs, and destroys it when the effect scope is disposed.
diff --git a/docs/framework/vue/guides/hotkeys.md b/docs/framework/vue/guides/hotkeys.md
index 87e178c9..b60854af 100644
--- a/docs/framework/vue/guides/hotkeys.md
+++ b/docs/framework/vue/guides/hotkeys.md
@@ -5,6 +5,18 @@ id: hotkeys
The `useHotkey` composable is the primary way to register keyboard shortcuts in Vue applications. It wraps the singleton `HotkeyManager` with automatic cleanup, support for template refs, and reactive option syncing.
+## Chords and sequences
+
+A hotkey is either a **chord**, keys pressed together such as `'Mod+S'`, or a **sequence**, chords pressed one after another such as `['G', 'G']`. Every API in this guide accepts both, and a one-step array such as `['Mod+S']` is the chord `'Mod+S'`.
+
+```ts
+useHotkey('Mod+S', () => save()) // chord
+useHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 }) // sequence
+useHotkey('Escape', () => close(), { requireReset: true }) // chord-only option
+```
+
+Most options apply to both kinds. `requireReset` applies only to chords and `timeout` only to sequences, and TypeScript rejects options that don't match the hotkey. When the kind isn't known statically, such as a `Hotkey` loaded from settings, only the shared options are accepted. Defaults apply only to the kinds that support them. See the [Sequences Guide](./sequences) for timing and matching, and the [App Hotkeys Guide](./app-hotkeys) to declare hotkeys up front and let users customize them.
+
## Logical keys and physical positions
Use a logical binding when the shortcut should follow the character on the active layout. Use a physical binding when it should follow a keyboard position:
@@ -252,39 +264,31 @@ Group is descriptive metadata, not an execution scope. A shortcuts panel can gro
## Introspecting registrations
-Use the `useHotkeyRegistrations` composable to get a live view of all hotkey and sequence registrations. It works well for shortcut palettes, help dialogs, and devtools.
+Use the `useHotkeyRegistrations` composable to get a live view of every registration, chords and sequences together. It's the building block for shortcut palettes and help dialogs.
```vue
-
```
-The returned `hotkeys` array contains registration objects with the hotkey string, options (including `meta`), and enabled state. The `sequences` array contains sequence registrations with the same structure.
+The returned ref holds one array of registration views. Each view has an `id`, the `hotkey`, its `options` (including `meta`), its `target`, and a `triggerCount`. Narrow with `kind`: chord views add `parsedHotkey`; sequence views add `parsedSequence` and `matchedStepCount`, the steps matched so far in the current attempt. Disabled entries stay listed; unmounted registrations disappear. Format any hotkey with `formatForDisplay`, and group entries by `options.meta?.group` when building a help panel.
+
+Registrations only exist while their components are mounted. To list hotkeys from routes that have not rendered, declare them with [app hotkeys](./app-hotkeys).
## The hotkey manager
diff --git a/docs/framework/vue/guides/key-state-tracking.md b/docs/framework/vue/guides/key-state-tracking.md
index 8dd69fe3..3f2c44fe 100644
--- a/docs/framework/vue/guides/key-state-tracking.md
+++ b/docs/framework/vue/guides/key-state-tracking.md
@@ -105,6 +105,6 @@ tracker.isKeyHeld('Shift')
const visible = useHotkeyHint(() => binding.value) // computed ref: visible.value
```
-For `Alt+Shift+[KeyK]`, holding Alt, Shift, or both reveals the hint. An extra Control hides it; releasing all modifiers or blurring the window hides it. Nonmodifier keys are ignored. AltGraph does not reveal hints. Pass `{ exact: true }` to require all binding modifiers, or `{ platform: 'mac' }` to resolve Mod explicitly. Supply the same platform used by the registration when overriding detection.
+For `Alt+Shift+[KeyK]`, holding Alt, Shift, or both reveals the hint. An extra Control hides it; releasing all modifiers or blurring the window hides it. Nonmodifier keys are ignored. AltGraph does not reveal hints. Pass `{ exact: true }` to require all binding modifiers, or `{ platform: 'mac' }` to resolve Mod explicitly. Supply the same platform used by the registration when overriding detection. A sequence reveals its hint from its first step, and an app hotkey uses its effective hotkey (no hint while unbound).
Combine the boolean with the action's enabled state. The helper does not register a shortcut or determine whether its target is focused. The core equivalent is `matchesHeldModifiers(binding, heldKeys, options)`.
diff --git a/docs/framework/vue/guides/sequence-recording.md b/docs/framework/vue/guides/sequence-recording.md
deleted file mode 100644
index 5815ebfa..00000000
--- a/docs/framework/vue/guides/sequence-recording.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-title: Sequence Recording Guide
-id: sequence-recording
----
-
-TanStack Hotkeys provides the `useHotkeySequenceRecorder` composable for building UIs where users record multi-chord sequences (Vim-style shortcuts). The recorder captures each step like a single hotkey chord. Users finish with Enter by default, or you can use manual commit and an optional idle timeout.
-
-Sequence recording uses `recordBy: 'code'` by default, preserving every step as a physical string such as `['[KeyG]', 'Alt+[KeyS]']`. Set `recordBy: 'key'` for logical characters. The shared rejection and conflict options follow the [hotkey recording guide](./hotkey-recording.md#validation-and-conflicts).
-
-TanStack Hotkeys automatically suppresses registered hotkey and sequence callbacks while any recorder is active. You do not need to set `enabled` from `isRecording`. Registrations remain available for conflict detection, and recorded keys stay suppressed through repeats and key release.
-
-## Reactive options
-
-Recorder options support [property getters and functions returning options](./hotkeys.md#property-getters). Updated callbacks, validation, and recording settings apply during an active session without restarting it. Allow the framework to run its effect or watcher before relying on the update.
-
-## Basic usage
-
-```vue
-
-
-
-
-
-
-
-
-```
-
-## Return value
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `isRecording` | `boolean` | Whether the recorder is listening |
-| `steps` | `HotkeySequence` | Chords captured in the current session |
-| `recordedSequence` | `HotkeySequence \| null` | Last committed sequence |
-| `startRecording` | `() => void` | Start a new session |
-| `stopRecording` | `() => void` | Stop without calling `onRecord` |
-| `cancelRecording` | `() => void` | Stop and call `onCancel` |
-| `commitRecording` | `() => void` | Commit current `steps` (no-op if empty) |
-
-## Options
-
-`recordBy` defaults to `'code'`; choose `'key'` for logical characters. Repeats and IME composition never append steps. Modifier-only presses wait for a complete chord.
-
-Core options live on `HotkeySequenceRecorderOptions` from `@tanstack/hotkeys`:
-
-- `onRecord(sequence)`: called when a nonempty sequence is committed. Clearing calls only `onClear`.
-- `onCancel`, `onClear`: same intent as the hotkey recorder.
-- `commitKeys`: `'enter'` (default) or `'none'`. With `'none'`, only `commitRecording()` (or `idleTimeoutMs`) finishes recording; plain Enter can be recorded as a chord.
-- `commitOnEnter`: when `commitKeys` is `'enter'`, set to `false` to treat Enter as a normal chord (then use `commitRecording()` or idle timeout to finish).
-- `idleTimeoutMs`: optional milliseconds of inactivity after the last completed chord to auto-commit. The timer does not run while waiting for the first chord.
-
-### Provider defaults
-
-```vue
-
-
-
-```
-
-### `ignoreInputs`
-
-The `HotkeySequenceRecorderOptions` supports an `ignoreInputs` option (defaults to `true`). When `true`, the recorder doesn't 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 an input has focus. Set `ignoreInputs: false` if you want the recorder to capture keys from within input elements.
-
-## Validation and conflicts
-
-Sequence `validate(sequence, { events, parsedSequence })` runs when committing and returns true, false, or a rejection message. `detectConflicts` checks sequence prefixes as well as single bindings. Rejected commits keep recording active with the steps intact so the user can edit them with Backspace. Empty Backspace/Delete clears and emits `onClear` only; removing a nonempty step does not commit. Recorded steps, commit keys, and releases are isolated from application handlers.
-
-## Behavior
-
-| Input | Behavior |
-|-------|----------|
-| Valid chord | Appended to `steps`; listener stays active |
-| Enter (no modifiers), `commitKeys: 'enter'`, `steps.length >= 1` | Commits and calls `onRecord` |
-| Escape | Cancels; `onCancel` |
-| Backspace / Delete (no modifiers) | Removes last step, or if empty runs only `onClear` and stops |
-
-Recorded chords use portable `Mod` format, same as `HotkeyRecorder`.
-
-## Under the hood
-
-`useHotkeySequenceRecorder` wraps the `HotkeySequenceRecorder` class and subscribes to its TanStack Store, same pattern as `useHotkeyRecorder`.
diff --git a/docs/framework/vue/guides/sequences.md b/docs/framework/vue/guides/sequences.md
index a176f839..0c53f195 100644
--- a/docs/framework/vue/guides/sequences.md
+++ b/docs/framework/vue/guides/sequences.md
@@ -3,148 +3,145 @@ title: Sequences Guide
id: sequences
---
-TanStack Hotkeys supports multi-key sequences in Vue, where keys are pressed one after another rather than simultaneously.
+A sequence is a hotkey made of chords pressed one after another rather than together. Think Vim-style navigation, cheat codes, or multi-step commands. Sequences are ordinary hotkeys: register them with `useHotkey` and `useHotkeys`, list them with `useHotkeyRegistrations`, record them with `useHotkeyRecorder`, and format them with `formatForDisplay`.
-Sequence steps use the same string syntax as single hotkeys. For example, `['[KeyG]', '[KeyG]']` follows a physical position, while `['G', 'G']` follows the logical letter. A sequence can mix forms, such as `['Mod+[KeyK]', 'C']`. Display steps with `sequence.map((step) => formatForDisplay(step)).join(' → ')`.
-
-## Reactive options
-
-Sequence options support the same [property getter patterns](./hotkeys.md#property-getters) as hotkey options, including `enabled`, `timeout`, and `target`. Updates preserve the registration when its sequence, target, and platform stay the same.
+Sequence steps use the same syntax as chords. For example, `['[KeyG]', '[KeyG]']` follows a physical position, while `['G', 'G']` follows the logical letter. A sequence can mix forms, such as `['Mod+[KeyK]', 'C']`.
## Basic usage
+Pass an array of chords wherever you pass a hotkey:
+
```vue
```
+The user must press the steps in order, each within the timeout window. A one-step array such as `['Escape']` is the chord `'Escape'`.
+
## Many sequences at once
-When you need several sequences, or a reactive list whose length changes, use `useHotkeySequences` instead of many `useHotkeySequence` calls. One composable registers every sequence safely.
+`useHotkeys` registers chords and sequences together, including dynamic lists:
-```vue
-
```
-Options merge like `useHotkeys`: `HotkeysProvider` defaults, then `commonOptions`, then each definition's `options`.
-
-## Matching steps
-
-Both `SequenceManager` and `createSequenceMatcher` ignore modifier-only events, IME composition, and automatic keydown repeats. These events neither advance the sequence nor refresh its timeout: holding G does not complete a two-press G sequence. The manager prefers exact matches over weaker logical-key fallbacks while preserving equally strong matches.
-
## Sequence options
-```ts
-useHotkeySequence(['G', 'G'], callback, {
- timeout: 1000,
- enabled: true,
-})
-```
+Sequences accept the same options as chords, except `requireReset`, plus `timeout`.
-### Reactive `enabled`
+### `timeout`
-When disabled, the sequence stays registered (visible in devtools); only execution is suppressed.
-
-```vue
-
+// Slow sequence - user has more time between keys
+useHotkey(['Shift+Z', 'Shift+Z'], () => forceQuit(), { timeout: 2000 })
```
-## Global defaults via provider
+`timeout` is only accepted when the hotkey is a sequence. Set a default for every sequence with `HotkeysProvider` (or `provideHotkeysContext` in a root component's setup):
```vue
-
-
-
-
+
+
```
-### `meta`
+### `enabled` and `meta`
-Sequences support the same `meta` option as hotkeys. Attach a `name` and `description` to use in shortcut palettes and devtools.
+These work exactly as they do for chords. Disabled sequences stay registered and visible in devtools, and `meta` flows to registrations, devtools, and cheat sheets. See the [Hotkeys Guide](./hotkeys).
```ts
-useHotkeySequence(['G', 'G'], () => scrollToTop(), {
- meta: { name: 'Go to Top', description: 'Scroll to the top of the page' },
-})
+useHotkey(['G', 'G'], () => scrollToTop(), () => ({
+ enabled: isVimMode.value,
+ meta: { name: 'Go to top', description: 'Scroll to the top of the page' },
+}))
```
-See the [Hotkeys Guide](./hotkeys.md#metadata-name--description) for details on declaration merging and introspecting registrations.
-
-## Chained modifier chords
+## Sequences with modifiers
-This example follows physical R and T positions. Brackets retain those positions even when the keys produce different letters. Other sequences can continue using logical characters.
-
-Each step can use modifiers (for example `Mod+K` then `Mod+C`). You can use the same modifier on consecutive steps:
+Each step in a sequence can include modifiers, and consecutive steps can repeat the same modifier:
```ts
-useHotkeySequence(['Shift+[KeyR]', 'Shift+[KeyT]'], () => doNextAction())
-```
+// Ctrl+K followed by Ctrl+C (VS Code-style comment)
+useHotkey(['Mod+K', 'Mod+C'], () => commentSelection())
-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. A user can press Shift alone between `Shift+R` and `Shift+T` without breaking the sequence.
+// Physical R then T positions, both with Shift
+useHotkey(['Shift+[KeyR]', 'Shift+[KeyT]'], () => doNextAction())
+```
-## Common patterns
+Brackets retain physical positions even when the keys produce different letters. While a sequence is in progress, modifier-only keydown events (Shift, Control, Alt, or Meta pressed alone) are ignored. They neither advance the sequence nor reset progress, so a user can tap or hold Shift between `Shift+R` and `Shift+T`.
-### Vim-style navigation
+## Vim-style navigation
```ts
-useHotkeySequence(['G', 'G'], () => scrollToTop())
-useHotkeySequence(['G', 'Shift+G'], () => scrollToBottom())
-useHotkeySequence(['D', 'D'], () => deleteLine())
-useHotkeySequence(['D', 'W'], () => deleteWord())
-useHotkeySequence(['C', 'I', 'W'], () => changeInnerWord())
+useHotkeys([
+ { hotkey: ['G', 'G'], callback: () => scrollToTop() },
+ { hotkey: ['G', 'Shift+G'], callback: () => scrollToBottom() },
+ { hotkey: ['D', 'D'], callback: () => deleteLine() },
+ { hotkey: ['D', 'W'], callback: () => deleteWord() },
+ { hotkey: ['C', 'I', 'W'], callback: () => changeInnerWord() },
+])
```
-### Konami Code
+## Displaying sequences
+
+`formatForDisplay` formats each step and joins them with `sequenceSeparator`, a space by default:
```ts
-useHotkeySequence(
- ['ArrowUp', 'ArrowUp', 'ArrowDown', 'ArrowDown', 'B', 'A'],
- () => enableEasterEgg(),
- { timeout: 2000 },
-)
+formatForDisplay(['Mod+K', 'Mod+C'], { platform: 'mac' }) // '⌘ K ⌘ C'
+formatForDisplay(['G', 'G'], { sequenceSeparator: ' then ' }) // 'G then G'
```
-## Under the hood
+Registration views report each sequence's progress in `matchedStepCount`, so a help panel can show how far the user has typed. See the [Hotkeys Guide](./hotkeys).
-`useHotkeySequence` uses the singleton `SequenceManager`. You can also access it directly:
+## How sequences work
-```ts
-import { createSequenceMatcher, getSequenceManager } from '@tanstack/vue-hotkeys'
+The `HotkeyManager` tracks progress for every sequence registration. When a key is pressed:
-const manager = getSequenceManager()
-const matcher = createSequenceMatcher(['G', 'G'], { timeout: 1000 })
-```
+1. It checks whether the key matches the next expected step of each sequence
+2. If it matches, that sequence advances
+3. If the timeout expires between steps, the sequence resets
+4. When all steps are completed, the callback fires
+
+Modifier-only events, IME composition, and automatic keydown repeats neither advance a sequence nor refresh its timeout: holding G does not complete a two-press G sequence. Exact matches take priority over weaker logical-key fallbacks.
+
+Multiple sequences can share a prefix, such as `['D', 'D']`, `['D', 'W']`, and `['D', 'I', 'W']`. Progress is tracked for each sequence independently, so after pressing `D` the manager waits for the next key to determine which sequence completes.
### Conflicting registrations
-For the same target, duplicate detection compares resolved steps: modifier aliases, modifier order, and logical key casing do not create separate bindings. `conflictBehavior` applies to equivalent sequences without rewriting their stored strings. Physical and logical identities remain distinct, and a shared prefix alone is not a duplicate registration. Recorder conflict detection also checks prefixes and observed physical/logical overlap.
+For the same target, duplicate detection compares resolved steps: modifier aliases, modifier order, and logical key casing do not create separate hotkeys. Physical and logical identities remain distinct, and a shared prefix alone is not a duplicate registration. Recorder conflict detection and app hotkey conflicts are stricter: there, a sequence also conflicts with a chord equal to its first step and with any sequence it starts.
+
+## Standalone matching
+
+For sequence matching without the singleton manager, use `createSequenceMatcher`:
+
+```ts
+import { createSequenceMatcher } from '@tanstack/vue-hotkeys'
+
+const matcher = createSequenceMatcher(['G', 'G'], { timeout: 1000 })
+
+document.addEventListener('keydown', (e) => {
+ if (matcher.match(e)) {
+ console.log('Sequence completed!')
+ }
+ console.log('Progress:', matcher.getProgress()) // e.g., 1
+})
+```
diff --git a/docs/framework/vue/quick-start.md b/docs/framework/vue/quick-start.md
index 2e53388f..597955b9 100644
--- a/docs/framework/vue/quick-start.md
+++ b/docs/framework/vue/quick-start.md
@@ -81,14 +81,15 @@ useHotkey('Escape', () => {
```vue
```
-For several sequences or a list that changes at runtime, prefer a single `useHotkeySequences([...])` call (see the [Sequences guide](./guides/sequences.md#many-sequences-at-once)).
+For several sequences or a list that changes at runtime, prefer a single `useHotkeys([...])` call (see the [Sequences guide](./guides/sequences.md#many-sequences-at-once)).
### Tracking held keys
@@ -136,8 +137,7 @@ import { HotkeysProvider } from '@tanstack/vue-hotkeys'
@@ -146,11 +146,15 @@ import { HotkeysProvider } from '@tanstack/vue-hotkeys'
```
+## Declaring app hotkeys
+
+To list every hotkey in a cheat sheet, including hotkeys whose components haven't mounted, and to let users customize them, declare them once with `defineAppHotkeys` and provide them with `HotkeysProvider`. See the [App Hotkeys Guide](./guides/app-hotkeys).
+
## Next steps
- [Hotkeys Guide](./guides/hotkeys)
- [Sequences Guide](./guides/sequences)
- [Hotkey Recording Guide](./guides/hotkey-recording)
-- [Sequence Recording Guide](./guides/sequence-recording)
+- [App Hotkeys Guide](./guides/app-hotkeys)
- [Key State Tracking Guide](./guides/key-state-tracking)
- [Formatting & Display Guide](./guides/formatting-display)
diff --git a/docs/framework/vue/reference/functions/provideHotkeysContext.md b/docs/framework/vue/reference/functions/provideHotkeysContext.md
index 43d888ed..66e33512 100644
--- a/docs/framework/vue/reference/functions/provideHotkeysContext.md
+++ b/docs/framework/vue/reference/functions/provideHotkeysContext.md
@@ -4,17 +4,32 @@ title: provideHotkeysContext
---
```ts
-function provideHotkeysContext(defaultOptions?): void;
+function provideHotkeysContext(options?): void;
```
-Defined in: [HotkeysProviderContext.ts:26](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L26)
+Defined in: [HotkeysProviderContext.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L69)
+
+Provides default options, app hotkeys, and the user's custom hotkeys to
+descendants. `HotkeysProvider` calls this; call it directly in a root
+component's setup instead of rendering the provider.
## Parameters
-### defaultOptions?
+### options?
-`MaybeRefOrGetter`\<[`HotkeysProviderOptions`](../interfaces/HotkeysProviderOptions.md)\>
+[`ProvideHotkeysContextOptions`](../interfaces/ProvideHotkeysContextOptions.md) = `{}`
## Returns
`void`
+
+## Example
+
+```ts
+provideHotkeysContext({
+ appHotkeys,
+ customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ onCustomHotkeysChange: (custom) =>
+ localStorage.setItem('hotkeys', JSON.stringify(custom)),
+})
+```
diff --git a/docs/framework/vue/reference/functions/useAppHotkeyList.md b/docs/framework/vue/reference/functions/useAppHotkeyList.md
new file mode 100644
index 00000000..ee133fee
--- /dev/null
+++ b/docs/framework/vue/reference/functions/useAppHotkeyList.md
@@ -0,0 +1,18 @@
+---
+id: useAppHotkeyList
+title: useAppHotkeyList
+---
+
+```ts
+function useAppHotkeyList(): ComputedRef>[]>;
+```
+
+Defined in: [useAppHotkeys.ts:48](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L48)
+
+Lists every app hotkey with its live status, in declaration order, for
+cheat sheets and settings screens. App hotkeys whose components have not
+mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+
+## Returns
+
+`ComputedRef`\<`AppHotkeyListItem`\<`AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>\>[]\>
diff --git a/docs/framework/vue/reference/functions/useAppHotkeys.md b/docs/framework/vue/reference/functions/useAppHotkeys.md
new file mode 100644
index 00000000..b93e4f9e
--- /dev/null
+++ b/docs/framework/vue/reference/functions/useAppHotkeys.md
@@ -0,0 +1,24 @@
+---
+id: useAppHotkeys
+title: useAppHotkeys
+---
+
+```ts
+function useAppHotkeys(): ComputedRef>>>;
+```
+
+Defined in: [useAppHotkeys.ts:35](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L35)
+
+Returns a computed ref of the effective app hotkeys from `HotkeysProvider`,
+typed by `Register`: each declaration with the user's custom hotkey applied.
+
+## Returns
+
+`ComputedRef`\<`Readonly`\<`Record`\<`string`, `AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>\>\>\>
+
+## Example
+
+```ts
+const hotkeys = useAppHotkeys()
+useHotkey(() => hotkeys.value['doc.save'], () => save())
+```
diff --git a/docs/framework/vue/reference/functions/useCustomHotkeys.md b/docs/framework/vue/reference/functions/useCustomHotkeys.md
new file mode 100644
index 00000000..53c966ac
--- /dev/null
+++ b/docs/framework/vue/reference/functions/useCustomHotkeys.md
@@ -0,0 +1,18 @@
+---
+id: useCustomHotkeys
+title: useCustomHotkeys
+---
+
+```ts
+function useCustomHotkeys(): UseCustomHotkeysResult;
+```
+
+Defined in: [useAppHotkeys.ts:87](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L87)
+
+Reads and changes the user's custom hotkeys. Changes apply to every
+registered app hotkey immediately and are emitted by the provider as
+`custom-hotkeys-change`, ready to save.
+
+## Returns
+
+[`UseCustomHotkeysResult`](../interfaces/UseCustomHotkeysResult.md)
diff --git a/docs/framework/vue/reference/functions/useDefaultHotkeysOptions.md b/docs/framework/vue/reference/functions/useDefaultHotkeysOptions.md
index 1f316c09..8e184ce5 100644
--- a/docs/framework/vue/reference/functions/useDefaultHotkeysOptions.md
+++ b/docs/framework/vue/reference/functions/useDefaultHotkeysOptions.md
@@ -7,7 +7,7 @@ title: useDefaultHotkeysOptions
function useDefaultHotkeysOptions(): HotkeysProviderOptions;
```
-Defined in: [HotkeysProviderContext.ts:42](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L42)
+Defined in: [HotkeysProviderContext.ts:109](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L109)
## Returns
diff --git a/docs/framework/vue/reference/functions/useHotkey.md b/docs/framework/vue/reference/functions/useHotkey.md
index e48c0333..0b6a8e5b 100644
--- a/docs/framework/vue/reference/functions/useHotkey.md
+++ b/docs/framework/vue/reference/functions/useHotkey.md
@@ -3,93 +3,106 @@ id: useHotkey
title: useHotkey
---
+## Call Signature
+
```ts
-function useHotkey(
+function useHotkey(
hotkey,
callback,
options?): void;
```
-Defined in: [useHotkey.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L99)
-
-Vue composable for registering a keyboard hotkey.
+Defined in: [useHotkey.ts:75](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L75)
-Uses the singleton HotkeyManager for efficient event handling.
-The callback receives both the keyboard event and a context object
-containing the hotkey string and parsed hotkey.
+Vue composable for registering a hotkey: a chord such as `'Mod+S'`, a
+sequence such as `['G', 'G']`, or an app hotkey from `defineAppHotkeys`.
+The hotkey and options may be refs or getters.
-This composable automatically tracks reactive dependencies and updates
-the registration when options or the callback change.
+Chords accept `requireReset`; sequences accept `timeout`. A one-step
+sequence registers as its chord. An app hotkey uses its effective hotkey
+from `HotkeysProvider` (including the user's custom hotkey) and its
+declared meta and options, and registers nothing while unbound.
-## Parameters
+### Type Parameters
-### hotkey
+#### T
-`MaybeRefOrGetter`\<`RegisterableHotkey`\>
+`T` *extends* `AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>
-The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+### Parameters
-### callback
+#### hotkey
-`HotkeyCallback`
+`MaybeRefOrGetter`\<`T`\>
-The function to call when the hotkey is pressed
+#### callback
-### options?
+`HotkeyCallback`
-`MaybeRefOrGetter`\<[`UseHotkeyOptions`](../interfaces/UseHotkeyOptions.md)\> = `{}`
+#### options?
-Options for the hotkey behavior
+`MaybeRefOrGetter`\<[`UseAppHotkeyOptions`](../type-aliases/UseAppHotkeyOptions.md)\<`T`\>\>
-## Returns
+### Returns
`void`
-## Examples
+### Example
-```vue
-
+```ts
+function useHotkey(
+ hotkey,
+ callback,
+ options?): void;
```
-```vue
-
-```
+Chords accept `requireReset`; sequences accept `timeout`. A one-step
+sequence registers as its chord. An app hotkey uses its effective hotkey
+from `HotkeysProvider` (including the user's custom hotkey) and its
+declared meta and options, and registers nothing while unbound.
+
+### Type Parameters
-```vue
-
+### Parameters
-
-
...
-
+#### hotkey
+
+`MaybeRefOrGetter`\<`T`\>
+
+#### callback
+
+`HotkeyCallback`
+
+#### options?
+
+`MaybeRefOrGetter`\<[`UseHotkeyOptionsFor`](../type-aliases/UseHotkeyOptionsFor.md)\<`T`\>\>
+
+### Returns
+
+`void`
+
+### Example
+
+```ts
+useHotkey('Mod+S', () => save())
+useHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
+useHotkey('Escape', () => close(), { enabled: isOpen })
```
diff --git a/docs/framework/vue/reference/functions/useHotkeyHint.md b/docs/framework/vue/reference/functions/useHotkeyHint.md
index 5d982332..dda117d5 100644
--- a/docs/framework/vue/reference/functions/useHotkeyHint.md
+++ b/docs/framework/vue/reference/functions/useHotkeyHint.md
@@ -7,19 +7,21 @@ title: useHotkeyHint
function useHotkeyHint(hotkey, options?): ComputedRef;
```
-Defined in: [useHotkeyHint.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyHint.ts#L14)
+Defined in: [useHotkeyHint.ts:24](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyHint.ts#L24)
Returns a computed ref indicating whether held modifiers reveal this shortcut.
-Pass refs or getters to track changing bindings and options.
-Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
-every modifier. Combine with the action's enabled state before showing a badge.
-This helper does not register a shortcut or check whether its target is focused.
+Pass refs or getters to track changing hotkeys and options. A sequence
+reveals its hint from its first step, and an app hotkey uses its effective
+hotkey (false while unbound). This helper does not register a shortcut or
+check whether its target is focused.
## Parameters
### hotkey
-`MaybeRefOrGetter`\<`RegisterableHotkey`\>
+`MaybeRefOrGetter`\<
+ \| `AppHotkey`\<`string`, HotkeyChord \| HotkeySequence \| null\>
+ \| `RegisterableHotkey`\>
### options?
diff --git a/docs/framework/vue/reference/functions/useHotkeyRecorder.md b/docs/framework/vue/reference/functions/useHotkeyRecorder.md
index bdd20bf6..566ee7eb 100644
--- a/docs/framework/vue/reference/functions/useHotkeyRecorder.md
+++ b/docs/framework/vue/reference/functions/useHotkeyRecorder.md
@@ -3,60 +3,162 @@ id: useHotkeyRecorder
title: useHotkeyRecorder
---
+## Call Signature
+
+```ts
+function useHotkeyRecorder(options): VueHotkeyRecorder;
+```
+
+Defined in: [useHotkeyRecorder.ts:46](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L46)
+
+Vue composable for recording keyboard shortcuts. Options may be a ref or getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+`HotkeyChordRecorderOptions`
+
+### Returns
+
+[`VueHotkeyRecorder`](../interfaces/VueHotkeyRecorder.md)\<`HotkeyChord`\>
+
+### Example
+
+```ts
+const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
+const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
+```
+
+## Call Signature
+
+```ts
+function useHotkeyRecorder(options): VueHotkeyRecorder;
+```
+
+Defined in: [useHotkeyRecorder.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L49)
+
+Vue composable for recording keyboard shortcuts. Options may be a ref or getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+`HotkeySequenceRecorderOptions`
+
+### Returns
+
+[`VueHotkeyRecorder`](../interfaces/VueHotkeyRecorder.md)
+
+### Example
+
+```ts
+const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
+const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
+```
+
+## Call Signature
+
```ts
function useHotkeyRecorder(options): VueHotkeyRecorder;
```
-Defined in: [useHotkeyRecorder.ts:62](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L62)
+Defined in: [useHotkeyRecorder.ts:54](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L54)
-Vue composable for recording keyboard shortcuts.
+Vue composable for recording keyboard shortcuts. Options may be a ref or getter.
-This composable provides a thin wrapper around the framework-agnostic `HotkeyRecorder`
-class, managing all the complexity of capturing keyboard events, converting them
-to hotkey strings, and handling edge cases like Escape to cancel or Backspace/Delete
-to clear.
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
-## Parameters
+### Parameters
-### options
+#### options
-`MaybeRefOrGetter`\<`HotkeyRecorderOptions`\>
+() => `HotkeySequenceRecorderOptions`
-Configuration options for the recorder
+### Returns
-## Returns
+[`VueHotkeyRecorder`](../interfaces/VueHotkeyRecorder.md)
+
+### Example
+
+```ts
+const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
+const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
+```
+
+## Call Signature
+
+```ts
+function useHotkeyRecorder(options): VueHotkeyRecorder;
+```
+
+Defined in: [useHotkeyRecorder.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L57)
+
+Vue composable for recording keyboard shortcuts. Options may be a ref or getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+() => `HotkeyChordRecorderOptions`
+
+### Returns
+
+[`VueHotkeyRecorder`](../interfaces/VueHotkeyRecorder.md)\<`HotkeyChord`\>
+
+### Example
+
+```ts
+const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
+const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
+```
+
+## Call Signature
+
+```ts
+function useHotkeyRecorder(options): VueHotkeyRecorder;
+```
+
+Defined in: [useHotkeyRecorder.ts:60](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L60)
+
+Vue composable for recording keyboard shortcuts. Options may be a ref or getter.
+
+With the default `maxSteps: 1`, the first valid chord is recorded. With a
+larger `maxSteps`, each chord adds a step; the recording commits on Enter
+(unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+`onRecord` receives a chord (one step) or a sequence.
+
+### Parameters
+
+#### options
+
+`Ref`\<`HotkeyRecorderOptions`\>
+
+### Returns
[`VueHotkeyRecorder`](../interfaces/VueHotkeyRecorder.md)
-An object with recording state and control functions
-
-## Example
-
-```vue
-
-
-
-
-
-
- Recording: {{ recorder.recordedHotkey }}
-
-
-
+### Example
+
+```ts
+const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
+const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
```
diff --git a/docs/framework/vue/reference/functions/useHotkeyRegistrations.md b/docs/framework/vue/reference/functions/useHotkeyRegistrations.md
index 202549f4..a4c0a020 100644
--- a/docs/framework/vue/reference/functions/useHotkeyRegistrations.md
+++ b/docs/framework/vue/reference/functions/useHotkeyRegistrations.md
@@ -4,20 +4,31 @@ title: useHotkeyRegistrations
---
```ts
-function useHotkeyRegistrations(): HotkeyRegistrationsResult;
+function useHotkeyRegistrations(): Readonly>;
```
-Defined in: [useHotkeyRegistrations.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRegistrations.ts#L33)
+Defined in: [useHotkeyRegistrations.ts:26](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRegistrations.ts#L26)
-Vue composable that reactively reads all hotkey and sequence registrations
-from the singleton managers.
+Vue composable that reactively reads every hotkey registration, chords and
+sequences, from the singleton HotkeyManager. Narrow each view with `kind`.
-This is a standalone composable that does NOT require the HotkeysProvider.
-It subscribes to both HotkeyManager and SequenceManager stores and
-triggers reactivity when registrations change.
+This composable does NOT require the HotkeysProvider.
## Returns
-[`HotkeyRegistrationsResult`](../interfaces/HotkeyRegistrationsResult.md)
+`Readonly`\<`Ref`\<`HotkeyRegistrationView`[]\>\>
-Object with `hotkeys` and `sequences` refs
+A ref of all registrations, without callbacks
+
+## Example
+
+```vue
+
+
+
+
+```
diff --git a/docs/framework/vue/reference/functions/useHotkeySequence.md b/docs/framework/vue/reference/functions/useHotkeySequence.md
deleted file mode 100644
index d8848b38..00000000
--- a/docs/framework/vue/reference/functions/useHotkeySequence.md
+++ /dev/null
@@ -1,79 +0,0 @@
----
-id: useHotkeySequence
-title: useHotkeySequence
----
-
-```ts
-function useHotkeySequence(
- sequence,
- callback,
- options?): void;
-```
-
-Defined in: [useHotkeySequence.ts:76](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequence.ts#L76)
-
-Vue composable for registering a keyboard shortcut sequence (Vim-style).
-
-This composable allows you to register multi-key sequences like 'g g' or 'd d'
-that trigger when the full sequence is pressed within a timeout.
-
-Each step may include modifiers. You can chain the same modifier across
-steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
-Control, Alt, or Meta pressed alone) are ignored while matching—they do not
-advance the sequence or reset progress.
-
-## Parameters
-
-### sequence
-
-`MaybeRefOrGetter`\<`HotkeySequence`\>
-
-Array of hotkey strings that form the sequence
-
-### callback
-
-`HotkeyCallback`
-
-Function to call when the sequence is completed
-
-### options?
-
-`MaybeRefOrGetter`\<[`UseHotkeySequenceOptions`](../interfaces/UseHotkeySequenceOptions.md)\> = `{}`
-
-Options for the sequence behavior
-
-## Returns
-
-`void`
-
-## Example
-
-```vue
-
-
-
-
...
-
-```
diff --git a/docs/framework/vue/reference/functions/useHotkeySequenceRecorder.md b/docs/framework/vue/reference/functions/useHotkeySequenceRecorder.md
deleted file mode 100644
index 4a37a79c..00000000
--- a/docs/framework/vue/reference/functions/useHotkeySequenceRecorder.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: useHotkeySequenceRecorder
-title: useHotkeySequenceRecorder
----
-
-```ts
-function useHotkeySequenceRecorder(options): VueHotkeySequenceRecorder;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:24](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L24)
-
-Vue composable for recording multi-chord sequences (Vim-style shortcuts).
-
-## Parameters
-
-### options
-
-`MaybeRefOrGetter`\<`HotkeySequenceRecorderOptions`\>
-
-## Returns
-
-[`VueHotkeySequenceRecorder`](../interfaces/VueHotkeySequenceRecorder.md)
diff --git a/docs/framework/vue/reference/functions/useHotkeySequences.md b/docs/framework/vue/reference/functions/useHotkeySequences.md
deleted file mode 100644
index cbae9270..00000000
--- a/docs/framework/vue/reference/functions/useHotkeySequences.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-id: useHotkeySequences
-title: useHotkeySequences
----
-
-```ts
-function useHotkeySequences(definitions, commonOptions?): void;
-```
-
-Defined in: [useHotkeySequences.ts:68](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequences.ts#L68)
-
-Vue composable for registering multiple keyboard shortcut sequences at once (Vim-style).
-
-Uses the singleton SequenceManager. Accepts a dynamic array of definitions, or a getter/ref
-that returns one, so you can register variable-length lists safely.
-
-Options are merged in this order:
-HotkeysProvider defaults < commonOptions < per-definition options
-
-Definitions with an empty `sequence` are skipped (no registration).
-
-## Parameters
-
-### definitions
-
-`MaybeRefOrGetter`\<[`UseHotkeySequenceDefinition`](../interfaces/UseHotkeySequenceDefinition.md)[]\>
-
-Array of sequence definitions, or a getter/ref
-
-### commonOptions?
-
-`MaybeRefOrGetter`\<[`UseHotkeySequenceOptions`](../interfaces/UseHotkeySequenceOptions.md)\> = `{}`
-
-Shared options applied to all sequences (overridden by per-definition options)
-
-## Returns
-
-`void`
-
-## Examples
-
-```vue
-
-```
-
-```vue
-
-```
diff --git a/docs/framework/vue/reference/functions/useHotkeys.md b/docs/framework/vue/reference/functions/useHotkeys.md
index 030f4d44..673d359d 100644
--- a/docs/framework/vue/reference/functions/useHotkeys.md
+++ b/docs/framework/vue/reference/functions/useHotkeys.md
@@ -7,63 +7,35 @@ title: useHotkeys
function useHotkeys(hotkeys, commonOptions?): void;
```
-Defined in: [useHotkeys.ts:73](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L73)
+Defined in: [useHotkeys.ts:90](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L90)
-Vue composable for registering multiple keyboard hotkeys at once.
+Vue composable for registering several hotkeys at once: chords, sequences,
+and app hotkeys. The list, each hotkey, and options may be refs or getters.
-Uses the singleton HotkeyManager for efficient event handling.
-Accepts a dynamic array of hotkey definitions, making it safe to use
-with variable-length lists.
-
-Options are merged in this order:
-HotkeysProvider defaults < commonOptions < per-definition options
+Options merge in this order: provider defaults, app hotkey declaration,
+commonOptions, per-hotkey options. Each option applies only to the kinds
+that support it. Unbound app hotkeys and empty sequences register nothing.
+A target that resolves to `null` skips registration until it is set.
## Parameters
### hotkeys
-`MaybeRefOrGetter`\<[`UseHotkeyDefinition`](../interfaces/UseHotkeyDefinition.md)[]\>
-
-Array of hotkey definitions to register, or a getter/ref
+`MaybeRefOrGetter`\
### commonOptions?
-`MaybeRefOrGetter`\<[`UseHotkeyOptions`](../interfaces/UseHotkeyOptions.md)\> = `{}`
-
-Shared options applied to all hotkeys (overridden by per-definition options)
+`MaybeRefOrGetter`\<[`UseHotkeyCommonOptions`](../type-aliases/UseHotkeyCommonOptions.md)\> = `{}`
## Returns
`void`
-## Examples
-
-```vue
-
-```
-
-```vue
-
```
diff --git a/docs/framework/vue/reference/functions/useHotkeysContext.md b/docs/framework/vue/reference/functions/useHotkeysContext.md
index b853d9e3..9f8fa8f2 100644
--- a/docs/framework/vue/reference/functions/useHotkeysContext.md
+++ b/docs/framework/vue/reference/functions/useHotkeysContext.md
@@ -7,7 +7,7 @@ title: useHotkeysContext
function useHotkeysContext(): HotkeysContextValue | null;
```
-Defined in: [HotkeysProviderContext.ts:38](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L38)
+Defined in: [HotkeysProviderContext.ts:105](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L105)
## Returns
diff --git a/docs/framework/vue/reference/index.md b/docs/framework/vue/reference/index.md
index 78df6d3f..991b6187 100644
--- a/docs/framework/vue/reference/index.md
+++ b/docs/framework/vue/reference/index.md
@@ -5,14 +5,21 @@ title: "@tanstack/vue-hotkeys"
## Interfaces
-- [HotkeyRegistrationsResult](interfaces/HotkeyRegistrationsResult.md)
- [HotkeysProviderOptions](interfaces/HotkeysProviderOptions.md)
-- [UseHotkeyDefinition](interfaces/UseHotkeyDefinition.md)
-- [UseHotkeyOptions](interfaces/UseHotkeyOptions.md)
-- [UseHotkeySequenceDefinition](interfaces/UseHotkeySequenceDefinition.md)
-- [UseHotkeySequenceOptions](interfaces/UseHotkeySequenceOptions.md)
+- [ProvideHotkeysContextOptions](interfaces/ProvideHotkeysContextOptions.md)
+- [UseCustomHotkeysResult](interfaces/UseCustomHotkeysResult.md)
- [VueHotkeyRecorder](interfaces/VueHotkeyRecorder.md)
-- [VueHotkeySequenceRecorder](interfaces/VueHotkeySequenceRecorder.md)
+
+## Type Aliases
+
+- [UseAppHotkeyOptions](type-aliases/UseAppHotkeyOptions.md)
+- [UseHotkeyChordOptions](type-aliases/UseHotkeyChordOptions.md)
+- [UseHotkeyCommonOptions](type-aliases/UseHotkeyCommonOptions.md)
+- [UseHotkeyDefinition](type-aliases/UseHotkeyDefinition.md)
+- [UseHotkeyOptions](type-aliases/UseHotkeyOptions.md)
+- [UseHotkeyOptionsFor](type-aliases/UseHotkeyOptionsFor.md)
+- [UseHotkeySequenceOptions](type-aliases/UseHotkeySequenceOptions.md)
+- [UseHotkeyTarget](type-aliases/UseHotkeyTarget.md)
## Variables
@@ -21,6 +28,9 @@ title: "@tanstack/vue-hotkeys"
## Functions
- [provideHotkeysContext](functions/provideHotkeysContext.md)
+- [useAppHotkeyList](functions/useAppHotkeyList.md)
+- [useAppHotkeys](functions/useAppHotkeys.md)
+- [useCustomHotkeys](functions/useCustomHotkeys.md)
- [useDefaultHotkeysOptions](functions/useDefaultHotkeysOptions.md)
- [useHeldKeyCodes](functions/useHeldKeyCodes.md)
- [useHeldKeys](functions/useHeldKeys.md)
@@ -30,7 +40,4 @@ title: "@tanstack/vue-hotkeys"
- [useHotkeyRegistrations](functions/useHotkeyRegistrations.md)
- [useHotkeys](functions/useHotkeys.md)
- [useHotkeysContext](functions/useHotkeysContext.md)
-- [useHotkeySequence](functions/useHotkeySequence.md)
-- [useHotkeySequenceRecorder](functions/useHotkeySequenceRecorder.md)
-- [useHotkeySequences](functions/useHotkeySequences.md)
- [useKeyHold](functions/useKeyHold.md)
diff --git a/docs/framework/vue/reference/interfaces/HotkeyRegistrationsResult.md b/docs/framework/vue/reference/interfaces/HotkeyRegistrationsResult.md
deleted file mode 100644
index 4f34bb59..00000000
--- a/docs/framework/vue/reference/interfaces/HotkeyRegistrationsResult.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-id: HotkeyRegistrationsResult
-title: HotkeyRegistrationsResult
----
-
-Defined in: [useHotkeyRegistrations.ts:16](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRegistrations.ts#L16)
-
-Return type for useHotkeyRegistrations.
-
-## Properties
-
-### hotkeys
-
-```ts
-hotkeys: Ref;
-```
-
-Defined in: [useHotkeyRegistrations.ts:18](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRegistrations.ts#L18)
-
-All registered hotkeys (public view, no callbacks)
-
-***
-
-### sequences
-
-```ts
-sequences: Ref;
-```
-
-Defined in: [useHotkeyRegistrations.ts:20](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRegistrations.ts#L20)
-
-All registered sequences
diff --git a/docs/framework/vue/reference/interfaces/HotkeysProviderOptions.md b/docs/framework/vue/reference/interfaces/HotkeysProviderOptions.md
index ef313fd5..87b23a43 100644
--- a/docs/framework/vue/reference/interfaces/HotkeysProviderOptions.md
+++ b/docs/framework/vue/reference/interfaces/HotkeysProviderOptions.md
@@ -3,44 +3,29 @@ id: HotkeysProviderOptions
title: HotkeysProviderOptions
---
-Defined in: [HotkeysProviderContext.ts:10](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L10)
+Defined in: [HotkeysProviderContext.ts:12](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L12)
## Properties
### hotkey?
```ts
-optional hotkey?: Partial;
+optional hotkey?: UseHotkeyCommonOptions;
```
-Defined in: [HotkeysProviderContext.ts:11](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L11)
-
-***
-
-### hotkeyRecorder?
-
-```ts
-optional hotkeyRecorder?: Partial;
-```
+Defined in: [HotkeysProviderContext.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L17)
-Defined in: [HotkeysProviderContext.ts:12](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L12)
+Defaults for every hotkey registered by `useHotkey` and `useHotkeys`.
+`requireReset` applies to chords and `timeout` applies to sequences.
***
-### hotkeySequence?
+### hotkeyRecorder?
```ts
-optional hotkeySequence?: Partial;
+optional hotkeyRecorder?: Partial>;
```
-Defined in: [HotkeysProviderContext.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L14)
-
-***
-
-### hotkeySequenceRecorder?
-
-```ts
-optional hotkeySequenceRecorder?: Partial;
-```
+Defined in: [HotkeysProviderContext.ts:19](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L19)
-Defined in: [HotkeysProviderContext.ts:13](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L13)
+Defaults for every `useHotkeyRecorder`.
diff --git a/docs/framework/vue/reference/interfaces/ProvideHotkeysContextOptions.md b/docs/framework/vue/reference/interfaces/ProvideHotkeysContextOptions.md
new file mode 100644
index 00000000..73b8db0c
--- /dev/null
+++ b/docs/framework/vue/reference/interfaces/ProvideHotkeysContextOptions.md
@@ -0,0 +1,70 @@
+---
+id: ProvideHotkeysContextOptions
+title: ProvideHotkeysContextOptions
+---
+
+Defined in: [HotkeysProviderContext.ts:38](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L38)
+
+Options for `provideHotkeysContext`.
+
+## Properties
+
+### appHotkeys?
+
+```ts
+optional appHotkeys?: MaybeRefOrGetter<
+ | Readonly>>
+| undefined>;
+```
+
+Defined in: [HotkeysProviderContext.ts:44](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L44)
+
+Every app hotkey, from `defineAppHotkeys`. Read when the context is
+provided; later changes update the declarations.
+
+***
+
+### customHotkeys?
+
+```ts
+optional customHotkeys?:
+ | CustomHotkeys>>>
+ | null;
+```
+
+Defined in: [HotkeysProviderContext.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L49)
+
+Starting custom hotkeys, such as saved data. Read once; the context owns
+the state afterwards. Invalid entries are ignored with a warning.
+
+***
+
+### defaultOptions?
+
+```ts
+optional defaultOptions?: MaybeRefOrGetter;
+```
+
+Defined in: [HotkeysProviderContext.ts:39](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L39)
+
+***
+
+### onCustomHotkeysChange?
+
+```ts
+optional onCustomHotkeysChange?: (customHotkeys) => void;
+```
+
+Defined in: [HotkeysProviderContext.ts:51](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProviderContext.ts#L51)
+
+Called with the custom hotkeys after every change, ready to save.
+
+#### Parameters
+
+##### customHotkeys
+
+`CustomHotkeys`
+
+#### Returns
+
+`void`
diff --git a/docs/framework/vue/reference/interfaces/UseCustomHotkeysResult.md b/docs/framework/vue/reference/interfaces/UseCustomHotkeysResult.md
new file mode 100644
index 00000000..0f8147b7
--- /dev/null
+++ b/docs/framework/vue/reference/interfaces/UseCustomHotkeysResult.md
@@ -0,0 +1,111 @@
+---
+id: UseCustomHotkeysResult
+title: UseCustomHotkeysResult
+---
+
+Defined in: [useAppHotkeys.ts:60](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L60)
+
+Custom hotkey state and actions returned by `useCustomHotkeys`.
+
+## Properties
+
+### customHotkeys
+
+```ts
+customHotkeys: ComputedRef>>>>;
+```
+
+Defined in: [useAppHotkeys.ts:62](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L62)
+
+The user's hotkeys that differ from the defaults.
+
+***
+
+### findConflicts
+
+```ts
+findConflicts: (id, hotkey) => AppHotkey[];
+```
+
+Defined in: [useAppHotkeys.ts:76](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L76)
+
+Other app hotkeys that would collide if `id` used `hotkey`.
+
+#### Parameters
+
+##### id
+
+`string`
+
+##### hotkey
+
+`Hotkey`
+
+#### Returns
+
+`AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>[]
+
+***
+
+### resetCustomHotkey
+
+```ts
+resetCustomHotkey: (id) => void;
+```
+
+Defined in: [useAppHotkeys.ts:72](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L72)
+
+Restores the default hotkey for an app hotkey.
+
+#### Parameters
+
+##### id
+
+`string`
+
+#### Returns
+
+`void`
+
+***
+
+### resetCustomHotkeys
+
+```ts
+resetCustomHotkeys: () => void;
+```
+
+Defined in: [useAppHotkeys.ts:74](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L74)
+
+Restores every default hotkey.
+
+#### Returns
+
+`void`
+
+***
+
+### setCustomHotkey
+
+```ts
+setCustomHotkey: (id, hotkey) => AppHotkey[];
+```
+
+Defined in: [useAppHotkeys.ts:67](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useAppHotkeys.ts#L67)
+
+Sets the user's hotkey for an app hotkey. `null` unbinds it.
+Returns conflicting app hotkeys; when any exist, nothing changes.
+
+#### Parameters
+
+##### id
+
+`string`
+
+##### hotkey
+
+`Hotkey` \| `null`
+
+#### Returns
+
+`AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>[]
diff --git a/docs/framework/vue/reference/interfaces/UseHotkeyDefinition.md b/docs/framework/vue/reference/interfaces/UseHotkeyDefinition.md
deleted file mode 100644
index 718f35af..00000000
--- a/docs/framework/vue/reference/interfaces/UseHotkeyDefinition.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-id: UseHotkeyDefinition
-title: UseHotkeyDefinition
----
-
-Defined in: [useHotkeys.ts:19](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L19)
-
-A single hotkey definition for use with `useHotkeys`.
-
-## Properties
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [useHotkeys.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L23)
-
-The function to call when the hotkey is pressed
-
-***
-
-### hotkey
-
-```ts
-hotkey: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkeys.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L21)
-
-The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object
-
-***
-
-### options?
-
-```ts
-optional options?: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkeys.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L25)
-
-Per-hotkey options (merged on top of commonOptions)
diff --git a/docs/framework/vue/reference/interfaces/UseHotkeyOptions.md b/docs/framework/vue/reference/interfaces/UseHotkeyOptions.md
deleted file mode 100644
index b668007d..00000000
--- a/docs/framework/vue/reference/interfaces/UseHotkeyOptions.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: UseHotkeyOptions
-title: UseHotkeyOptions
----
-
-Defined in: [useHotkey.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L17)
-
-## Extends
-
-- `Omit`\<`HotkeyOptions`, `"enabled"` \| `"target"`\>
-
-## Properties
-
-### enabled?
-
-```ts
-optional enabled?: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkey.ts:26](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L26)
-
-Whether the hotkey is active.
-Can be a Ref, a getter function, or a boolean value.
-Defaults to true.
-
-***
-
-### target?
-
-```ts
-optional target?: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkey.ts:32](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L32)
-
-The DOM element to attach the event listener to.
-Can be a Ref, a getter function, direct DOM element, or null.
-Defaults to document.
diff --git a/docs/framework/vue/reference/interfaces/UseHotkeySequenceDefinition.md b/docs/framework/vue/reference/interfaces/UseHotkeySequenceDefinition.md
deleted file mode 100644
index 6cd5de1a..00000000
--- a/docs/framework/vue/reference/interfaces/UseHotkeySequenceDefinition.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-id: UseHotkeySequenceDefinition
-title: UseHotkeySequenceDefinition
----
-
-Defined in: [useHotkeySequences.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequences.ts#L15)
-
-A single sequence definition for use with `useHotkeySequences`.
-
-## Properties
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [useHotkeySequences.ts:19](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequences.ts#L19)
-
-The function to call when the sequence is completed
-
-***
-
-### options?
-
-```ts
-optional options?: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkeySequences.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequences.ts#L21)
-
-Per-sequence options (merged on top of commonOptions)
-
-***
-
-### sequence
-
-```ts
-sequence: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkeySequences.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequences.ts#L17)
-
-Array of hotkey strings that form the sequence
diff --git a/docs/framework/vue/reference/interfaces/UseHotkeySequenceOptions.md b/docs/framework/vue/reference/interfaces/UseHotkeySequenceOptions.md
deleted file mode 100644
index 26c2cc58..00000000
--- a/docs/framework/vue/reference/interfaces/UseHotkeySequenceOptions.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: UseHotkeySequenceOptions
-title: UseHotkeySequenceOptions
----
-
-Defined in: [useHotkeySequence.ts:12](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequence.ts#L12)
-
-## Extends
-
-- `Omit`\<`SequenceOptions`, `"enabled"` \| `"target"`\>
-
-## Properties
-
-### enabled?
-
-```ts
-optional enabled?: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkeySequence.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequence.ts#L21)
-
-Whether the sequence is active.
-Can be a Ref, a getter function, or a boolean value.
-Defaults to true.
-
-***
-
-### target?
-
-```ts
-optional target?: MaybeRefOrGetter;
-```
-
-Defined in: [useHotkeySequence.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequence.ts#L27)
-
-The DOM element to attach the event listener to.
-Can be a Ref, a getter function, direct DOM element, or null.
-Defaults to document.
diff --git a/docs/framework/vue/reference/interfaces/VueHotkeyRecorder.md b/docs/framework/vue/reference/interfaces/VueHotkeyRecorder.md
index bcc26a30..54b63f95 100644
--- a/docs/framework/vue/reference/interfaces/VueHotkeyRecorder.md
+++ b/docs/framework/vue/reference/interfaces/VueHotkeyRecorder.md
@@ -3,7 +3,13 @@ id: VueHotkeyRecorder
title: VueHotkeyRecorder
---
-Defined in: [useHotkeyRecorder.ts:8](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L8)
+Defined in: [useHotkeyRecorder.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L15)
+
+## Type Parameters
+
+### THotkey
+
+`THotkey` *extends* `Hotkey` = `Hotkey`
## Properties
@@ -13,9 +19,25 @@ Defined in: [useHotkeyRecorder.ts:8](https://github.com/TanStack/hotkeys/blob/ma
cancelRecording: () => void;
```
-Defined in: [useHotkeyRecorder.ts:18](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L18)
+Defined in: [useHotkeyRecorder.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L27)
-Cancel recording without saving
+Cancel recording and call onCancel
+
+#### Returns
+
+`void`
+
+***
+
+### commitRecording
+
+```ts
+commitRecording: () => void;
+```
+
+Defined in: [useHotkeyRecorder.ts:29](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L29)
+
+Commit the recorded steps now (multi-step recordings)
#### Returns
@@ -26,10 +48,10 @@ Cancel recording without saving
### isRecording
```ts
-isRecording: Ref;
+isRecording: Readonly>;
```
-Defined in: [useHotkeyRecorder.ts:10](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L10)
+Defined in: [useHotkeyRecorder.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L17)
Whether recording is currently active
@@ -38,12 +60,12 @@ Whether recording is currently active
### recordedHotkey
```ts
-recordedHotkey: Ref;
+recordedHotkey: Readonly>;
```
-Defined in: [useHotkeyRecorder.ts:12](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L12)
+Defined in: [useHotkeyRecorder.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L21)
-The currently recorded hotkey (for live preview)
+The last committed hotkey
***
@@ -53,7 +75,7 @@ The currently recorded hotkey (for live preview)
startRecording: () => void;
```
-Defined in: [useHotkeyRecorder.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L14)
+Defined in: [useHotkeyRecorder.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L23)
Start recording a new hotkey
@@ -63,15 +85,27 @@ Start recording a new hotkey
***
+### steps
+
+```ts
+steps: Readonly>;
+```
+
+Defined in: [useHotkeyRecorder.ts:19](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L19)
+
+Chords recorded so far in a multi-step recording (for live preview)
+
+***
+
### stopRecording
```ts
stopRecording: () => void;
```
-Defined in: [useHotkeyRecorder.ts:16](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L16)
+Defined in: [useHotkeyRecorder.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeyRecorder.ts#L25)
-Stop recording (same as cancel)
+Stop recording without calling onCancel
#### Returns
diff --git a/docs/framework/vue/reference/interfaces/VueHotkeySequenceRecorder.md b/docs/framework/vue/reference/interfaces/VueHotkeySequenceRecorder.md
deleted file mode 100644
index 5ee65750..00000000
--- a/docs/framework/vue/reference/interfaces/VueHotkeySequenceRecorder.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-id: VueHotkeySequenceRecorder
-title: VueHotkeySequenceRecorder
----
-
-Defined in: [useHotkeySequenceRecorder.ts:11](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L11)
-
-## Properties
-
-### cancelRecording
-
-```ts
-cancelRecording: () => void;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L17)
-
-#### Returns
-
-`void`
-
-***
-
-### commitRecording
-
-```ts
-commitRecording: () => void;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:18](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L18)
-
-#### Returns
-
-`void`
-
-***
-
-### isRecording
-
-```ts
-isRecording: Ref;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:12](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L12)
-
-***
-
-### recordedSequence
-
-```ts
-recordedSequence: Ref;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L14)
-
-***
-
-### startRecording
-
-```ts
-startRecording: () => void;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L15)
-
-#### Returns
-
-`void`
-
-***
-
-### steps
-
-```ts
-steps: Ref;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:13](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L13)
-
-***
-
-### stopRecording
-
-```ts
-stopRecording: () => void;
-```
-
-Defined in: [useHotkeySequenceRecorder.ts:16](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeySequenceRecorder.ts#L16)
-
-#### Returns
-
-`void`
diff --git a/docs/framework/vue/reference/type-aliases/UseAppHotkeyOptions.md b/docs/framework/vue/reference/type-aliases/UseAppHotkeyOptions.md
new file mode 100644
index 00000000..0fe6ce72
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseAppHotkeyOptions.md
@@ -0,0 +1,18 @@
+---
+id: UseAppHotkeyOptions
+title: UseAppHotkeyOptions
+---
+
+```ts
+type UseAppHotkeyOptions = WithReactiveEnabled>;
+```
+
+Defined in: [useHotkey.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L55)
+
+Call-site options for an app hotkey, typed by its declared default kind.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `AppHotkey` = `AppHotkey`
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeyChordOptions.md b/docs/framework/vue/reference/type-aliases/UseHotkeyChordOptions.md
new file mode 100644
index 00000000..cac8d354
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeyChordOptions.md
@@ -0,0 +1,12 @@
+---
+id: UseHotkeyChordOptions
+title: UseHotkeyChordOptions
+---
+
+```ts
+type UseHotkeyChordOptions = WithReactiveEnabled>;
+```
+
+Defined in: [useHotkey.ts:36](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L36)
+
+Options for a chord such as `'Mod+S'`.
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeyCommonOptions.md b/docs/framework/vue/reference/type-aliases/UseHotkeyCommonOptions.md
new file mode 100644
index 00000000..08b4d665
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeyCommonOptions.md
@@ -0,0 +1,12 @@
+---
+id: UseHotkeyCommonOptions
+title: UseHotkeyCommonOptions
+---
+
+```ts
+type UseHotkeyCommonOptions = WithReactiveEnabled>;
+```
+
+Defined in: [useHotkey.ts:46](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L46)
+
+Options applied to every hotkey, such as provider defaults. Each applies to the kinds that support it.
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeyDefinition.md b/docs/framework/vue/reference/type-aliases/UseHotkeyDefinition.md
new file mode 100644
index 00000000..98663b10
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeyDefinition.md
@@ -0,0 +1,166 @@
+---
+id: UseHotkeyDefinition
+title: UseHotkeyDefinition
+---
+
+```ts
+type UseHotkeyDefinition =
+ | {
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+};
+```
+
+Defined in: [useHotkeys.ts:36](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkeys.ts#L36)
+
+One hotkey for `useHotkeys`. The hotkey and options may be refs or getters.
+Chords accept `requireReset`; sequences accept `timeout`; hotkeys of unknown
+kind accept only shared options.
+
+## Union Members
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+The function to call when the hotkey is pressed
+
+#### hotkey
+
+```ts
+hotkey: MaybeRefOrGetter;
+```
+
+A chord string such as `'Mod+S'`, or a RawHotkey object
+
+#### options?
+
+```ts
+optional options?: MaybeRefOrGetter;
+```
+
+Per-hotkey options (merged on top of commonOptions)
+
+***
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+#### hotkey
+
+```ts
+hotkey: MaybeRefOrGetter;
+```
+
+A sequence such as `['G', 'G']`
+
+#### options?
+
+```ts
+optional options?: MaybeRefOrGetter;
+```
+
+***
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+#### hotkey
+
+```ts
+hotkey: MaybeRefOrGetter;
+```
+
+An app hotkey from `defineAppHotkeys`
+
+#### options?
+
+```ts
+optional options?: MaybeRefOrGetter;
+```
+
+***
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: MaybeRefOrGetter;
+ options?: MaybeRefOrGetter;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+#### hotkey
+
+```ts
+hotkey: MaybeRefOrGetter;
+```
+
+A hotkey whose kind is not known statically. Accepts only shared options.
+
+#### options?
+
+```ts
+optional options?: MaybeRefOrGetter;
+```
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeyOptions.md b/docs/framework/vue/reference/type-aliases/UseHotkeyOptions.md
new file mode 100644
index 00000000..8286af72
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeyOptions.md
@@ -0,0 +1,12 @@
+---
+id: UseHotkeyOptions
+title: UseHotkeyOptions
+---
+
+```ts
+type UseHotkeyOptions = WithReactiveEnabled>;
+```
+
+Defined in: [useHotkey.ts:31](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L31)
+
+Options shared by chords and sequences.
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeyOptionsFor.md b/docs/framework/vue/reference/type-aliases/UseHotkeyOptionsFor.md
new file mode 100644
index 00000000..a9eb279f
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeyOptionsFor.md
@@ -0,0 +1,18 @@
+---
+id: UseHotkeyOptionsFor
+title: UseHotkeyOptionsFor
+---
+
+```ts
+type UseHotkeyOptionsFor = WithReactiveEnabled>;
+```
+
+Defined in: [useHotkey.ts:51](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L51)
+
+The options type for a hotkey: chord options for chords, sequence options for sequences.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `RegisterableHotkey`
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeySequenceOptions.md b/docs/framework/vue/reference/type-aliases/UseHotkeySequenceOptions.md
new file mode 100644
index 00000000..a3ff5388
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeySequenceOptions.md
@@ -0,0 +1,12 @@
+---
+id: UseHotkeySequenceOptions
+title: UseHotkeySequenceOptions
+---
+
+```ts
+type UseHotkeySequenceOptions = WithReactiveEnabled>;
+```
+
+Defined in: [useHotkey.ts:41](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L41)
+
+Options for a sequence such as `['G', 'G']`.
diff --git a/docs/framework/vue/reference/type-aliases/UseHotkeyTarget.md b/docs/framework/vue/reference/type-aliases/UseHotkeyTarget.md
new file mode 100644
index 00000000..c987db81
--- /dev/null
+++ b/docs/framework/vue/reference/type-aliases/UseHotkeyTarget.md
@@ -0,0 +1,13 @@
+---
+id: UseHotkeyTarget
+title: UseHotkeyTarget
+---
+
+```ts
+type UseHotkeyTarget = MaybeRefOrGetter;
+```
+
+Defined in: [useHotkey.ts:22](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/useHotkey.ts#L22)
+
+The element to listen on: a ref, getter, element, or null. A target that
+resolves to `null` skips registration until it is set. Defaults to document.
diff --git a/docs/framework/vue/reference/variables/HotkeysProvider.md b/docs/framework/vue/reference/variables/HotkeysProvider.md
index 4468f772..27e2668f 100644
--- a/docs/framework/vue/reference/variables/HotkeysProvider.md
+++ b/docs/framework/vue/reference/variables/HotkeysProvider.md
@@ -5,9 +5,19 @@ title: HotkeysProvider
```ts
const HotkeysProvider: DefineComponent>>>;
+ };
+ customHotkeys: {
+ default: undefined;
+ type: PropType<
+ | CustomHotkeys>>>
+ | null>;
+ };
defaultOptions: {
default: undefined;
- type: () => HotkeysProviderOptions;
+ type: PropType;
};
}>, () =>
| VNode true;
}, string, PublicProps, ToResolvedProps>>>;
+ };
+ customHotkeys: {
+ default: undefined;
+ type: PropType<
+ | CustomHotkeys>>>
+ | null>;
+ };
defaultOptions: {
default: undefined;
- type: () => HotkeysProviderOptions;
+ type: PropType;
};
}>, {
+ customHotkeysChange: (_customHotkeys) => true;
}>, {
+ appHotkeys: Readonly>>;
+ customHotkeys: | CustomHotkeys>>>
+ | null;
defaultOptions: HotkeysProviderOptions;
}, {
}, {
@@ -32,15 +57,21 @@ const HotkeysProvider: DefineComponent;
```
-Defined in: [HotkeysProvider.tsx:17](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProvider.tsx#L17)
+Defined in: [HotkeysProvider.tsx:25](https://github.com/TanStack/hotkeys/blob/main/packages/vue-hotkeys/src/HotkeysProvider.tsx#L25)
-Vue component that provides default options for hotkeys context.
+Vue component that provides default options, app hotkeys, and the user's
+custom hotkeys. `customHotkeys` is read once; listen to
+`custom-hotkeys-change` to save changes.
## Example
```vue
-
+
diff --git a/docs/installation.md b/docs/installation.md
index 9de86a90..50df94a5 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -27,155 +27,99 @@ Each framework package re-exports everything from the core `@tanstack/hotkeys` p
-### Alpine
-
-Use Alpine 3.15.12 or newer within version 3. Install the optional `hotkeysPlugin` before `Alpine.start()`, or create a scope explicitly.
-
-Start with the [Quick Start](./framework/alpine/quick-start), then follow the [guides](./framework/alpine/guides/hotkeys). The package includes the hotkeys adapter; a dedicated Alpine devtools adapter is not provided.
-
-
-
-
-
-### Ember
-
-Use Ember 6.8 or newer. Register hotkeys with imported template helpers in strict-mode `.gts` components. Pass the component as owner to state readers and recorders.
-
-Start with the [Quick Start](./framework/ember/quick-start), then follow the [guides](./framework/ember/guides/hotkeys). The package includes the hotkeys adapter; a dedicated Ember devtools adapter is not provided.
-
-
-
-
-
-### Octane
-
-Use Octane 0.1.36 or newer within version 0.1, with compiler-enabled `.tsrx` components. The Octane adapter requires Node.js 22.22.2 or newer when used in Node.js.
-
-Start with the [Quick Start](./framework/octane/quick-start), then follow the [guides](./framework/octane/guides/hotkeys). The package includes the hotkeys adapter; a dedicated Octane devtools adapter is not provided.
-
-
-
-
-
-### React
+# React
Start with the [Quick Start](./framework/react/quick-start) guide. If you want the integrated devtools panel, also install:
-
-
-
-
-### Preact
+# Preact
Start with the [API reference](./framework/preact/reference/index) and [guides](./framework/preact/guides/hotkeys). If you want the integrated devtools panel, also install:
-
-
-
-
-### Solid
+# Solid
Start with the [API reference](./framework/solid/reference/index) and [guides](./framework/solid/guides/hotkeys). If you want the integrated devtools panel, also install:
-
+# Angular
-
+Start with the [Quick Start](./framework/angular/quick-start) guide and the Angular-specific [guides](./framework/angular/guides/hotkeys).
-### Svelte
+The integrated devtools panel requires Angular 21 or newer. To use it, also install:
-Start with the [Quick Start](./framework/svelte/quick-start) guide and the Svelte-specific [guides](./framework/svelte/guides/hotkeys). If you want the integrated devtools panel, also install:
+# Vue
-
+Start with the [Quick Start](./framework/vue/quick-start) guide and the Vue-specific [guides](./framework/vue/guides/hotkeys).
-
+If you want the Vue devtools panel component, also install:
-### Angular
+# Svelte
-Start with the [Quick Start](./framework/angular/quick-start) guide and the Angular-specific [guides](./framework/angular/guides/hotkeys).
+Start with the [Quick Start](./framework/svelte/quick-start) guide and the Svelte-specific [guides](./framework/svelte/guides/hotkeys). If you want the integrated devtools panel, also install:
-The integrated devtools panel requires Angular 21 or newer. To use it, also install:
+# Lit
-
+Start with the [Quick Start](./framework/lit/quick-start) guide and the Lit-specific [guides](./framework/lit/guides/hotkeys).
-
+Lit currently ships the hotkeys adapter only, so no dedicated Lit devtools package is required.
-### Vue
+# Alpine
-Start with the [Quick Start](./framework/vue/quick-start) guide and the Vue-specific [guides](./framework/vue/guides/hotkeys).
+Use Alpine 3.15.12 or newer within version 3. Install the optional `hotkeysPlugin` before `Alpine.start()`, or create a scope explicitly.
-If you want the Vue devtools panel component, also install:
+Start with the [Quick Start](./framework/alpine/quick-start), then follow the [guides](./framework/alpine/guides/hotkeys). The package includes the hotkeys adapter; a dedicated Alpine devtools adapter is not provided.
-
+# Ember
-
+Use Ember 6.8 or newer. Register hotkeys with imported template helpers in strict-mode `.gts` components. Pass the component as owner to state readers and recorders.
-### Lit
+Start with the [Quick Start](./framework/ember/quick-start), then follow the [guides](./framework/ember/guides/hotkeys). The package includes the hotkeys adapter; a dedicated Ember devtools adapter is not provided.
-Start with the [Quick Start](./framework/lit/quick-start) guide and the Lit-specific [guides](./framework/lit/guides/hotkeys).
+# Octane
-Lit currently ships the hotkeys adapter only, so no dedicated Lit devtools package is required.
+Use Octane 0.1.36 or newer within version 0.1, with compiler-enabled `.tsrx` components. The Octane adapter requires Node.js 22.22.2 or newer when used in Node.js.
+
+Start with the [Quick Start](./framework/octane/quick-start), then follow the [guides](./framework/octane/guides/hotkeys). The package includes the hotkeys adapter; a dedicated Octane devtools adapter is not provided.
-angular: @tanstack/angular-devtools
-angular: @tanstack/angular-hotkeys-devtools
-svelte: @tanstack/svelte-devtools
-svelte: @tanstack/svelte-hotkeys-devtools
-preact: @tanstack/preact-devtools
-preact: @tanstack/preact-hotkeys-devtools
react: @tanstack/react-devtools
react: @tanstack/react-hotkeys-devtools
+preact: @tanstack/preact-devtools
+preact: @tanstack/preact-hotkeys-devtools
solid: @tanstack/solid-devtools
solid: @tanstack/solid-hotkeys-devtools
+angular: @tanstack/angular-devtools
+angular: @tanstack/angular-hotkeys-devtools
vue: @tanstack/vue-hotkeys-devtools
+svelte: @tanstack/svelte-devtools
+svelte: @tanstack/svelte-hotkeys-devtools
-### React
+# React
See the [devtools](./devtools) documentation for setup details.
-
-
-
-
-### Preact
+# Preact
See the [devtools](./devtools) documentation for setup details.
-
-
-
-
-### Solid
+# Solid
See the [devtools](./devtools) documentation for setup details.
-
-
-
-
-### Vue
+# Angular
See the [devtools](./devtools) documentation for setup details.
-
-
-
-
-### Angular
+# Vue
See the [devtools](./devtools) documentation for setup details.
-
-
-
-
-### Svelte
+# Svelte
See the [devtools](./devtools) documentation for setup details.
diff --git a/docs/overview.md b/docs/overview.md
index 61779a19..a046e567 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -3,70 +3,66 @@ title: Overview
id: overview
---
-TanStack Hotkeys is a type-safe, headless library for keyboard shortcuts, sequences, recording, and key state tracking. Use its framework adapters for registration and cleanup, and build shortcut interfaces with your own components and application state.
+TanStack Hotkeys is a type-safe, framework-agnostic library for keyboard shortcuts. It includes:
-## Runtime and package requirements
+- **Hotkey registration** for shortcuts like `Mod+S` and Vim-style sequences like `G G`
+- **App hotkeys** for global cheat-sheets and user-customizable shortcuts
+- **Hotkey recording** for shortcut settings screens
+- **Key state tracking** for held keys and modifier hints
+- **Display formatting** for platform-appropriate labels like `⌘ S` and `Ctrl+S`
+- **Devtools** for inspecting shortcuts while you develop
-Hotkeys packages ship ES2022 JavaScript as ESM only and require Node.js 20 or newer when used in Node.js, except the Octane adapter, which requires Node.js 22.22.2 or newer. Browser applications need an ES2022-compatible runtime or a build pipeline that transforms the library for their supported browsers.
+> [!IMPORTANT]
+> TanStack Hotkeys is currently in **alpha** and its API is still subject to change. Early adopters are encouraged to help us solve edge cases across multiple keyboard layouts, locales, and operating systems.
-Use ESM imports, such as `import { parseHotkey } from '@tanstack/hotkeys'`. CommonJS builds and `require` export conditions are no longer provided. CommonJS applications can use dynamic `import()` or migrate their consuming modules to ESM.
+## Motivation
-Published packages contain the runtime files and TypeScript declarations in `dist`, plus package metadata, README, and license files. The repository's `src` directory and source maps are no longer included. Inspect `dist/index.d.ts` and its referenced declarations for the installed API; consult the matching repository version when you need the original implementation.
+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. Browser keyboard events have their own edge cases too: key repeat, IME composition, and keys that look stuck after a missed key-up or a window switch.
-## Choose what a shortcut follows
+As an app grows, its shortcuts also end up scattered across components. Cheat sheets and settings screens are maintained by hand, drift out of sync with the actual hotkeys, and miss shortcuts on pages that haven't loaded yet.
-A binding can follow a logical character or a physical keyboard position. Both forms use the same registration APIs:
+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.
-```ts
-// React; the other adapters accept the same binding forms.
-useHotkey('Mod+S', save) // Logical S on the active layout
-useHotkey('Alt+[KeyW]', moveForward) // Physical KeyW position
-useHotkey({ code: 'NumpadAdd', mod: true }, zoomIn)
-```
+## Features
-`Mod` means Command on macOS and Control on Windows/Linux. Brackets identify physical `event.code` names in strings, including `[Enter]` and `[F13]`. Object bindings use either `key` or `code`, never both. Both logical names and physical codes have type-safe autocomplete.
+### Hotkey registration
-Logical bindings prefer `event.key`. ASCII letter output remains authoritative on layouts such as Dvorak and AZERTY; conservative code fallback helps when Option, dead keys, or non-Latin output transforms the character. Physical bindings match `event.code` exactly. Among eligible registrations on a target, exact matches take priority over weaker fallbacks.
+Register shortcuts such as `Mod+S` to save a document or `Escape` to close a dialog. `HotkeyManager` handles event listeners, conflict detection, and input filtering. Shortcuts can be enabled conditionally or scoped to a specific element, so a dialog's shortcuts can follow the dialog's lifetime.
-Logical and physical bindings both support F1–F24 and shared named keys such as `CapsLock`, `MediaPlayPause`, and `BrowserBack`. Some browser names differ: logical `LaunchApplication1` corresponds to physical `[LaunchApp1]`. Logical `Enter` includes numpad Enter, while `[Enter]` and `[NumpadEnter]` distinguish their positions.
+By default, TanStack Hotkeys prevents the browser's default action, stops event propagation, and filters shortcuts in input elements. These options are configurable when your application needs different behavior.
-## Register actions and sequences
+### Multi-key sequences
-Single shortcuts and sequence steps use the same binding syntax. For example, `['G', 'G']` follows the logical letter, while `['[KeyG]', '[KeyG]']` follows a position. Sequences may mix logical and physical steps. Modifier-only events, IME composition, and automatic repeats do not advance sequences or extend their timeout.
+Some shortcuts are a series of keystrokes instead of a single combination. Pass an array of chords anywhere a hotkey is accepted to register a Vim-style sequence such as `['G', 'G']` or `['D', 'I', 'W']`, with a configurable timeout between steps. Use sequences for navigation or commands when you want more shortcuts without adding more modifier keys.
-Registrations support enabled state, element targets, input handling, callback metadata, and conflict policies. Framework adapters update bindings from normal reactive state and remove them on unmount. `meta.name`, `meta.description`, and `meta.group` describe registrations for menus and help panels; they do not change matching or scope.
+### App hotkeys
-## Record a replacement binding
+Hotkeys registered by components only exist while those components are mounted. Declare every hotkey up front with `defineAppHotkeys` and pass the declarations to your framework's provider to list them in cheat sheets and settings screens, even on routes that have not loaded. Users can rebind or unbind any of them, conflicts are checked across every declaration, and your app decides where to save their custom hotkeys.
-Recorders default to `recordBy: 'code'`. On macOS, Option+S producing `ß` records `Alt+[KeyS]`, so replay follows the same physical combination. Set `recordBy: 'key'` to intentionally record the produced logical character. The recorder never silently switches between these modes.
+### Hotkey recording
-Pass recorded strings directly into registrations and store them in ordinary application state. Both single and sequence recorders support validation, structured rejection, and live-registry conflict checks. Rejected candidates leave recording active. Clearing calls only `onClear`; your app decides whether that removes a binding or restores an initial value.
+`HotkeyRecorder` captures a key combination so users can customize shortcuts in a settings UI. Set `maxSteps` to let users record a sequence too. It supports validation and conflict checks before you save a hotkey. You can register the recorded hotkey directly, store it in your application's state, or save it as an app hotkey's custom hotkey.
-## Display shortcuts and hints
+### Key state tracking
-Use `formatForDisplay` at render time. Both `Mod+S` and `Mod+[KeyS]` display as `⌘ S` on macOS, but their stored identities remain distinct. `parts: true` returns individual keycap labels, and symbols can be configured separately for modifiers and keys.
+`KeyStateTracker` tracks held keys and modifiers. Framework APIs such as `useHeldKeys`, `useHeldKeyCodes`, and `useKeyHold` let you respond while a key is down. Use them for keyboard controls, visual feedback, or hints that appear while a modifier is held.
-Physical labels use readable defaults such as `S`, `2`, and numpad labels. For a known layout, pass an already-resolved `layoutMap`; use `keyLabels` for explicit overrides. Formatting stays synchronous and never loads a keyboard layout. Labels do not change registration or recording behavior.
+### Type-safe, cross-platform bindings
-Key-state primitives expose held logical keys and physical codes. `matchesHeldModifiers` and framework hint helpers reveal relevant shortcuts while modifiers are held. Live registration views and devtools expose current shortcuts and sequence progress, making it possible to build grouped help panels without a separate action catalog.
+TypeScript autocomplete helps you write valid shortcut strings such as `Control+A`, `Alt+S`, or `Mod+Shift+G`. You can also use a `RawHotkey` object, such as `{ key: 'S', mod: true }`.
-## Inspect a binding
+`Mod` resolves to Command on macOS and Control on Windows and Linux, so the same binding works across operating systems. Logical shortcuts follow the character that was pressed, while physical shortcuts follow a keyboard position. This lets you choose between a letter-based command and a position-based control, such as movement in a game.
-`ParsedHotkey` preserves identity as a union: logical bindings have `key`, physical bindings have `code`. Narrow with `parsed.code !== undefined` before reading it. Shared resolved flags and the ordered modifier list live in `ParsedModifiers`. `parseKeyboardEvent` produces logical identity; code recording constructs physical identity explicitly.
+### Display formatting
-## Framework guides
+Format chords and sequences for menus, buttons, and cheat sheets with platform-appropriate labels, such as `⌘ S` on macOS and `Ctrl+S` on Windows. You can display a shortcut as text or individual keycaps while keeping its stored hotkey separate from its label.
-| Framework | Start here |
-| --- | --- |
-| Alpine | [Quick start](./framework/alpine/quick-start) |
-| Angular | [Quick start](./framework/angular/quick-start) |
-| Ember | [Quick start](./framework/ember/quick-start) |
-| Lit | [Quick start](./framework/lit/quick-start) |
-| Octane | [Quick start](./framework/octane/quick-start) |
-| Preact | [Hotkeys guide](./framework/preact/guides/hotkeys) |
-| React | [Quick start](./framework/react/quick-start) |
-| Solid | [Hotkeys guide](./framework/solid/guides/hotkeys) |
-| Svelte | [Quick start](./framework/svelte/quick-start) |
-| Vue | [Quick start](./framework/vue/quick-start) |
+### Framework adapters
-Explore a kitchen sink for [Alpine](./framework/alpine/examples/kitchen-sink), [Ember](./framework/ember/examples/kitchen-sink), [Octane](./framework/octane/examples/kitchen-sink), or [React](./framework/react/examples/kitchen-sink) to see route lifetimes, recording, and hints. Try the [vanilla formatter playground](./framework/vanilla/examples/formatForDisplay) for display options.
+Use React and Preact hooks, Solid primitives, Angular inject APIs, Vue composables, Lit controllers and decorators, Svelte reactive APIs, Alpine scopes, Ember helpers, or Octane hooks. The adapters connect hotkey registration and key state to your framework and clean up registrations when components unmount. You can also use the core utilities directly in vanilla JavaScript.
+
+### Devtools
+
+See registered hotkeys, declared app hotkeys, held keys, and sequence progress in real time. The [devtools](./devtools) help you inspect which shortcuts are active and how they are configured while developing your application.
+
+For a complete walkthrough, see the quick start for [React](framework/react/quick-start), [Preact](framework/preact/quick-start), [Solid](framework/solid/quick-start), [Angular](framework/angular/quick-start), [Vue](framework/vue/quick-start), [Svelte](framework/svelte/quick-start), [Lit](framework/lit/quick-start), [Alpine](framework/alpine/quick-start), [Ember](framework/ember/quick-start), or [Octane](framework/octane/quick-start).
diff --git a/docs/reference/adapter/functions/createHotkeyBindings.md b/docs/reference/adapter/functions/createHotkeyBindings.md
index bb0ba927..4fdf78d1 100644
--- a/docs/reference/adapter/functions/createHotkeyBindings.md
+++ b/docs/reference/adapter/functions/createHotkeyBindings.md
@@ -7,18 +7,16 @@ title: createHotkeyBindings
function createHotkeyBindings(): object;
```
-Defined in: [adapter.ts:107](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L107)
+Defined in: [adapter.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L53)
Reconciles adapter registrations while retaining handles for option updates.
## Returns
-`object`
-
-### destroy
+### destroy()
```ts
-destroy: () => void = bindings.destroy;
+destroy(): void;
```
#### Returns
@@ -31,15 +29,18 @@ destroy: () => void = bindings.destroy;
update(definitions, commonOptions?): void;
```
+Registers new definitions, updates existing ones in place, and removes
+stale ones. Definitions with an empty sequence or a null target are skipped.
+
#### Parameters
##### definitions
-[`HotkeyDefinition`](../interfaces/HotkeyDefinition.md)[]
+readonly [`HotkeyDefinition`](../type-aliases/HotkeyDefinition.md)[]
##### commonOptions?
-`HotkeyOptions` = `{}`
+[`HotkeyBindingsCommonOptions`](../type-aliases/HotkeyBindingsCommonOptions.md) = `{}`
#### Returns
diff --git a/docs/reference/adapter/functions/createHotkeySequenceBindings.md b/docs/reference/adapter/functions/createHotkeySequenceBindings.md
deleted file mode 100644
index f97db585..00000000
--- a/docs/reference/adapter/functions/createHotkeySequenceBindings.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-id: createHotkeySequenceBindings
-title: createHotkeySequenceBindings
----
-
-```ts
-function createHotkeySequenceBindings(): object;
-```
-
-Defined in: [adapter.ts:143](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L143)
-
-Reconciles sequence bindings; empty sequences and explicit null targets are skipped.
-
-## Returns
-
-`object`
-
-### destroy
-
-```ts
-destroy: () => void = bindings.destroy;
-```
-
-#### Returns
-
-`void`
-
-### update()
-
-```ts
-update(definitions, commonOptions?): void;
-```
-
-#### Parameters
-
-##### definitions
-
-[`HotkeySequenceDefinition`](../interfaces/HotkeySequenceDefinition.md)[]
-
-##### commonOptions?
-
-`SequenceOptions` = `{}`
-
-#### Returns
-
-`void`
diff --git a/docs/reference/adapter/functions/prepareHotkeyDefinitions.md b/docs/reference/adapter/functions/prepareHotkeyDefinitions.md
new file mode 100644
index 00000000..a410cc1a
--- /dev/null
+++ b/docs/reference/adapter/functions/prepareHotkeyDefinitions.md
@@ -0,0 +1,36 @@
+---
+id: prepareHotkeyDefinitions
+title: prepareHotkeyDefinitions
+---
+
+```ts
+function prepareHotkeyDefinitions(definitions, options?): HotkeyDefinition[];
+```
+
+Defined in: [adapter.ts:280](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L280)
+
+Converts adapter definitions into `createHotkeyBindings` definitions.
+Options merge in this order: defaults, app hotkey declaration, common
+options, per-definition options. App hotkeys resolve their effective hotkey
+from the store, and an unbound app hotkey keeps its position but registers
+nothing.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
+
+## Parameters
+
+### definitions
+
+readonly [`AdapterHotkeyDefinition`](../type-aliases/AdapterHotkeyDefinition.md)\<`TTarget`\>[]
+
+### options?
+
+[`PrepareHotkeyDefinitionsOptions`](../interfaces/PrepareHotkeyDefinitionsOptions.md)\<`TTarget`\> = `{}`
+
+## Returns
+
+[`HotkeyDefinition`](../type-aliases/HotkeyDefinition.md)[]
diff --git a/docs/reference/adapter/functions/subscribePublishedAppHotkeys.md b/docs/reference/adapter/functions/subscribePublishedAppHotkeys.md
new file mode 100644
index 00000000..778aa996
--- /dev/null
+++ b/docs/reference/adapter/functions/subscribePublishedAppHotkeys.md
@@ -0,0 +1,25 @@
+---
+id: subscribePublishedAppHotkeys
+title: subscribePublishedAppHotkeys
+---
+
+```ts
+function subscribePublishedAppHotkeys(onChange): () => void;
+```
+
+Defined in: [adapter.ts:319](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L319)
+
+Calls `onChange` when the store published with `publishAppHotkeysStore` or
+`provideAppHotkeys` changes, or when its app hotkeys or custom hotkeys
+change. For adapters that resolve app hotkeys without a provider. Returns an
+unsubscribe function.
+
+## Parameters
+
+### onChange
+
+() => `void`
+
+## Returns
+
+() => `void`
diff --git a/docs/reference/adapter/index.md b/docs/reference/adapter/index.md
index fec56d9d..17967895 100644
--- a/docs/reference/adapter/index.md
+++ b/docs/reference/adapter/index.md
@@ -5,10 +5,23 @@ title: "@tanstack/hotkeys"
## Interfaces
-- [HotkeyDefinition](interfaces/HotkeyDefinition.md)
-- [HotkeySequenceDefinition](interfaces/HotkeySequenceDefinition.md)
+- [PrepareHotkeyDefinitionsOptions](interfaces/PrepareHotkeyDefinitionsOptions.md)
+
+## Type Aliases
+
+- [AdapterAppHotkeyOptions](type-aliases/AdapterAppHotkeyOptions.md)
+- [AdapterChordOptions](type-aliases/AdapterChordOptions.md)
+- [AdapterCommonOptions](type-aliases/AdapterCommonOptions.md)
+- [AdapterHotkeyDefinition](type-aliases/AdapterHotkeyDefinition.md)
+- [AdapterHotkeyOptions](type-aliases/AdapterHotkeyOptions.md)
+- [AdapterOptionsFor](type-aliases/AdapterOptionsFor.md)
+- [AdapterSequenceOptions](type-aliases/AdapterSequenceOptions.md)
+- [HotkeyBindingsCommonOptions](type-aliases/HotkeyBindingsCommonOptions.md)
+- [HotkeyDefinition](type-aliases/HotkeyDefinition.md)
+- [WithTarget](type-aliases/WithTarget.md)
## Functions
- [createHotkeyBindings](functions/createHotkeyBindings.md)
-- [createHotkeySequenceBindings](functions/createHotkeySequenceBindings.md)
+- [prepareHotkeyDefinitions](functions/prepareHotkeyDefinitions.md)
+- [subscribePublishedAppHotkeys](functions/subscribePublishedAppHotkeys.md)
diff --git a/docs/reference/adapter/interfaces/HotkeyDefinition.md b/docs/reference/adapter/interfaces/HotkeyDefinition.md
deleted file mode 100644
index 17cd68d5..00000000
--- a/docs/reference/adapter/interfaces/HotkeyDefinition.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: HotkeyDefinition
-title: HotkeyDefinition
----
-
-Defined in: [adapter.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L14)
-
-A hotkey and its callback, with optional per-binding options.
-
-## Properties
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [adapter.ts:16](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L16)
-
-***
-
-### hotkey
-
-```ts
-hotkey: RegisterableHotkey;
-```
-
-Defined in: [adapter.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L15)
-
-***
-
-### options?
-
-```ts
-optional options?: HotkeyOptions;
-```
-
-Defined in: [adapter.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L17)
diff --git a/docs/reference/adapter/interfaces/HotkeySequenceDefinition.md b/docs/reference/adapter/interfaces/HotkeySequenceDefinition.md
deleted file mode 100644
index d09fe726..00000000
--- a/docs/reference/adapter/interfaces/HotkeySequenceDefinition.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: HotkeySequenceDefinition
-title: HotkeySequenceDefinition
----
-
-Defined in: [adapter.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L21)
-
-A sequence and its callback, with optional per-binding options.
-
-## Properties
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [adapter.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L23)
-
-***
-
-### options?
-
-```ts
-optional options?: SequenceOptions;
-```
-
-Defined in: [adapter.ts:24](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L24)
-
-***
-
-### sequence
-
-```ts
-sequence: HotkeySequence;
-```
-
-Defined in: [adapter.ts:22](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L22)
diff --git a/docs/reference/adapter/interfaces/PrepareHotkeyDefinitionsOptions.md b/docs/reference/adapter/interfaces/PrepareHotkeyDefinitionsOptions.md
new file mode 100644
index 00000000..8be14089
--- /dev/null
+++ b/docs/reference/adapter/interfaces/PrepareHotkeyDefinitionsOptions.md
@@ -0,0 +1,76 @@
+---
+id: PrepareHotkeyDefinitionsOptions
+title: PrepareHotkeyDefinitionsOptions
+---
+
+Defined in: [adapter.ts:258](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L258)
+
+Context for `prepareHotkeyDefinitions`.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
+
+## Properties
+
+### appHotkeysStore?
+
+```ts
+optional appHotkeysStore?:
+ | AppHotkeysStore>>>
+ | null;
+```
+
+Defined in: [adapter.ts:260](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L260)
+
+The provider's app hotkeys store, so app hotkeys use custom hotkeys.
+
+***
+
+### commonOptions?
+
+```ts
+optional commonOptions?: AdapterCommonOptions;
+```
+
+Defined in: [adapter.ts:264](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L264)
+
+Options for every definition, applied after app hotkey declarations.
+
+***
+
+### defaults?
+
+```ts
+optional defaults?: AdapterCommonOptions;
+```
+
+Defined in: [adapter.ts:262](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L262)
+
+Provider defaults, applied first.
+
+***
+
+### resolveTarget?
+
+```ts
+optional resolveTarget?: (target) => Target | null | undefined;
+```
+
+Defined in: [adapter.ts:270](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L270)
+
+Resolves a framework target, such as a ref. Return `undefined` for the
+document or `null` to skip registration until the target exists.
+Without it, targets pass through and `null` means document.
+
+#### Parameters
+
+##### target
+
+`TTarget`
+
+#### Returns
+
+`Target` \| `null` \| `undefined`
diff --git a/docs/reference/adapter/type-aliases/AdapterAppHotkeyOptions.md b/docs/reference/adapter/type-aliases/AdapterAppHotkeyOptions.md
new file mode 100644
index 00000000..f48fcd23
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterAppHotkeyOptions.md
@@ -0,0 +1,26 @@
+---
+id: AdapterAppHotkeyOptions
+title: AdapterAppHotkeyOptions
+---
+
+```ts
+type AdapterAppHotkeyOptions = Omit<[T["defaultHotkey"]] extends [HotkeySequence] ? AdapterSequenceOptions : [T["defaultHotkey"]] extends [HotkeyChord] ? AdapterChordOptions : AdapterCommonOptions, "meta">;
+```
+
+Defined in: [adapter.ts:209](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L209)
+
+Call-site options for an app hotkey. `meta` comes from the declaration.
+Kind-specific options follow the declared default: `requireReset` for a
+chord, `timeout` for a sequence, both for an app hotkey without a default.
+If the user rebinds it to the other kind, options for the old kind no
+longer apply.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `AppHotkey`
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/adapter/type-aliases/AdapterChordOptions.md b/docs/reference/adapter/type-aliases/AdapterChordOptions.md
new file mode 100644
index 00000000..a7cc7590
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterChordOptions.md
@@ -0,0 +1,18 @@
+---
+id: AdapterChordOptions
+title: AdapterChordOptions
+---
+
+```ts
+type AdapterChordOptions = WithTarget;
+```
+
+Defined in: [adapter.ts:176](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L176)
+
+Options for a chord such as `'Mod+S'`, with a framework target.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/adapter/type-aliases/AdapterCommonOptions.md b/docs/reference/adapter/type-aliases/AdapterCommonOptions.md
new file mode 100644
index 00000000..7f233152
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterCommonOptions.md
@@ -0,0 +1,18 @@
+---
+id: AdapterCommonOptions
+title: AdapterCommonOptions
+---
+
+```ts
+type AdapterCommonOptions = AdapterChordOptions & AdapterSequenceOptions;
+```
+
+Defined in: [adapter.ts:188](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L188)
+
+Options applied to every hotkey, such as defaults. Each applies to the kinds that support it.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/adapter/type-aliases/AdapterHotkeyDefinition.md b/docs/reference/adapter/type-aliases/AdapterHotkeyDefinition.md
new file mode 100644
index 00000000..84143253
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterHotkeyDefinition.md
@@ -0,0 +1,174 @@
+---
+id: AdapterHotkeyDefinition
+title: AdapterHotkeyDefinition
+---
+
+```ts
+type AdapterHotkeyDefinition =
+ | {
+ callback: HotkeyCallback;
+ hotkey: RegisterableHotkeyChord;
+ options?: AdapterChordOptions;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: HotkeySequence;
+ options?: AdapterSequenceOptions;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: AppHotkey;
+ options?: Omit, "meta">;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: RegisterableHotkey;
+ options?: AdapterHotkeyOptions;
+};
+```
+
+Defined in: [adapter.ts:223](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L223)
+
+One hotkey and its callback for adapter APIs such as `useHotkeys`. Chords
+accept `requireReset`; sequences accept `timeout`; hotkeys of unknown kind
+accept only shared options.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
+
+## Union Members
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: RegisterableHotkeyChord;
+ options?: AdapterChordOptions;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+The function to call when the hotkey is pressed
+
+#### hotkey
+
+```ts
+hotkey: RegisterableHotkeyChord;
+```
+
+A chord string such as `'Mod+S'`, or a RawHotkey object
+
+#### options?
+
+```ts
+optional options?: AdapterChordOptions;
+```
+
+Per-hotkey options (merged on top of common options)
+
+***
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: HotkeySequence;
+ options?: AdapterSequenceOptions;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+#### hotkey
+
+```ts
+hotkey: HotkeySequence;
+```
+
+A sequence such as `['G', 'G']`
+
+#### options?
+
+```ts
+optional options?: AdapterSequenceOptions;
+```
+
+***
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: AppHotkey;
+ options?: Omit, "meta">;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+#### hotkey
+
+```ts
+hotkey: AppHotkey;
+```
+
+An app hotkey from `defineAppHotkeys`. Kind-specific options apply
+only while its effective hotkey has that kind.
+
+#### options?
+
+```ts
+optional options?: Omit, "meta">;
+```
+
+***
+
+### Type Literal
+
+```ts
+{
+ callback: HotkeyCallback;
+ hotkey: RegisterableHotkey;
+ options?: AdapterHotkeyOptions;
+}
+```
+
+#### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+#### hotkey
+
+```ts
+hotkey: RegisterableHotkey;
+```
+
+A hotkey whose kind is not known statically, such as user data typed
+`Hotkey`. Accepts only shared options.
+
+#### options?
+
+```ts
+optional options?: AdapterHotkeyOptions;
+```
diff --git a/docs/reference/adapter/type-aliases/AdapterHotkeyOptions.md b/docs/reference/adapter/type-aliases/AdapterHotkeyOptions.md
new file mode 100644
index 00000000..9a329287
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterHotkeyOptions.md
@@ -0,0 +1,18 @@
+---
+id: AdapterHotkeyOptions
+title: AdapterHotkeyOptions
+---
+
+```ts
+type AdapterHotkeyOptions = WithTarget;
+```
+
+Defined in: [adapter.ts:173](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L173)
+
+Options shared by chords and sequences, with a framework target.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/adapter/type-aliases/AdapterOptionsFor.md b/docs/reference/adapter/type-aliases/AdapterOptionsFor.md
new file mode 100644
index 00000000..ba2d9e60
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterOptionsFor.md
@@ -0,0 +1,22 @@
+---
+id: AdapterOptionsFor
+title: AdapterOptionsFor
+---
+
+```ts
+type AdapterOptionsFor = [T] extends [never] ? AdapterCommonOptions : T extends readonly [unknown] ? AdapterChordOptions : T extends ReadonlyArray ? AdapterSequenceOptions : AdapterChordOptions;
+```
+
+Defined in: [adapter.ts:192](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L192)
+
+Chord options for chords, sequence options for sequences.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `RegisterableHotkey`
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/adapter/type-aliases/AdapterSequenceOptions.md b/docs/reference/adapter/type-aliases/AdapterSequenceOptions.md
new file mode 100644
index 00000000..275050f8
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/AdapterSequenceOptions.md
@@ -0,0 +1,18 @@
+---
+id: AdapterSequenceOptions
+title: AdapterSequenceOptions
+---
+
+```ts
+type AdapterSequenceOptions = WithTarget;
+```
+
+Defined in: [adapter.ts:182](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L182)
+
+Options for a sequence such as `['G', 'G']`, with a framework target.
+
+## Type Parameters
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/adapter/type-aliases/HotkeyBindingsCommonOptions.md b/docs/reference/adapter/type-aliases/HotkeyBindingsCommonOptions.md
new file mode 100644
index 00000000..f659186d
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/HotkeyBindingsCommonOptions.md
@@ -0,0 +1,12 @@
+---
+id: HotkeyBindingsCommonOptions
+title: HotkeyBindingsCommonOptions
+---
+
+```ts
+type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOptions;
+```
+
+Defined in: [adapter.ts:47](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L47)
+
+Options shared by every definition. Each option applies only to the kinds that support it.
diff --git a/docs/reference/adapter/type-aliases/HotkeyDefinition.md b/docs/reference/adapter/type-aliases/HotkeyDefinition.md
new file mode 100644
index 00000000..c3f5bf94
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/HotkeyDefinition.md
@@ -0,0 +1,23 @@
+---
+id: HotkeyDefinition
+title: HotkeyDefinition
+---
+
+```ts
+type HotkeyDefinition =
+ | {
+ callback: HotkeyCallback;
+ hotkey: RegisterableHotkeyChord;
+ options?: HotkeyChordOptions;
+}
+ | {
+ callback: HotkeyCallback;
+ hotkey: HotkeySequence;
+ options?: HotkeySequenceOptions;
+};
+```
+
+Defined in: [adapter.ts:34](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L34)
+
+A hotkey and its callback, with optional per-binding options. Chords accept
+`requireReset`; sequences accept `timeout`.
diff --git a/docs/reference/adapter/type-aliases/WithTarget.md b/docs/reference/adapter/type-aliases/WithTarget.md
new file mode 100644
index 00000000..d1b87c21
--- /dev/null
+++ b/docs/reference/adapter/type-aliases/WithTarget.md
@@ -0,0 +1,32 @@
+---
+id: WithTarget
+title: WithTarget
+---
+
+```ts
+type WithTarget = Omit & object;
+```
+
+Defined in: [adapter.ts:164](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/adapter.ts#L164)
+
+Options with a framework-specific target, such as a ref.
+
+## Type Declaration
+
+### target?
+
+```ts
+optional target?: TTarget;
+```
+
+The element to listen on. Defaults to document.
+
+## Type Parameters
+
+### TOptions
+
+`TOptions`
+
+### TTarget
+
+`TTarget`
diff --git a/docs/reference/classes/AppHotkeysStore.md b/docs/reference/classes/AppHotkeysStore.md
new file mode 100644
index 00000000..98eacd41
--- /dev/null
+++ b/docs/reference/classes/AppHotkeysStore.md
@@ -0,0 +1,303 @@
+---
+id: AppHotkeysStore
+title: AppHotkeysStore
+---
+
+Defined in: [app-hotkeys.ts:349](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L349)
+
+Holds declared app hotkeys and the user's custom hotkeys. Framework
+providers create one and expose it through hooks; devtools read it from
+`HotkeyManager.appHotkeys`.
+
+## Example
+
+```ts
+const store = new AppHotkeysStore(appHotkeys, {
+ customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ onCustomHotkeysChange: (custom) =>
+ localStorage.setItem('hotkeys', JSON.stringify(custom)),
+})
+store.setCustomHotkey('doc.save', 'Mod+Shift+S')
+```
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`AppHotkeys`](../type-aliases/AppHotkeys.md) = [`AppHotkeys`](../type-aliases/AppHotkeys.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new AppHotkeysStore(appHotkeys, options?): AppHotkeysStore;
+```
+
+Defined in: [app-hotkeys.ts:354](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L354)
+
+#### Parameters
+
+##### appHotkeys
+
+`T`
+
+##### options?
+
+[`AppHotkeysStoreOptions`](../interfaces/AppHotkeysStoreOptions.md)\<`T`\> = `{}`
+
+#### Returns
+
+`AppHotkeysStore`\<`T`\>
+
+## Properties
+
+### store
+
+```ts
+readonly store: Store>;
+```
+
+Defined in: [app-hotkeys.ts:350](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L350)
+
+## Accessors
+
+### appHotkeys
+
+#### Get Signature
+
+```ts
+get appHotkeys(): T;
+```
+
+Defined in: [app-hotkeys.ts:372](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L372)
+
+Effective app hotkeys.
+
+##### Returns
+
+`T`
+
+***
+
+### customHotkeys
+
+#### Get Signature
+
+```ts
+get customHotkeys(): CustomHotkeys;
+```
+
+Defined in: [app-hotkeys.ts:377](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L377)
+
+The user's hotkeys that differ from the defaults.
+
+##### Returns
+
+[`CustomHotkeys`](../type-aliases/CustomHotkeys.md)\<`T`\>
+
+## Methods
+
+### findConflicts()
+
+```ts
+findConflicts(id, hotkey): AppHotkey[];
+```
+
+Defined in: [app-hotkeys.ts:413](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L413)
+
+Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
+collide when their contexts match or either has no context, and their
+hotkeys are equal or one sequence starts with the other.
+
+#### Parameters
+
+##### id
+
+keyof `T` & `string`
+
+##### hotkey
+
+[`Hotkey`](../type-aliases/Hotkey.md)
+
+#### Returns
+
+[`AppHotkey`](../interfaces/AppHotkey.md)\<`string`,
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null`\>[]
+
+***
+
+### get()
+
+```ts
+get(id):
+ | AppHotkey
+ | undefined;
+```
+
+Defined in: [app-hotkeys.ts:404](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L404)
+
+Effective app hotkey for an id, or `undefined` when it is not declared.
+
+#### Parameters
+
+##### id
+
+`string`
+
+#### Returns
+
+ \| [`AppHotkey`](../interfaces/AppHotkey.md)\<`string`,
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null`\>
+ \| `undefined`
+
+***
+
+### getList()
+
+```ts
+getList(registrations): AppHotkeyListItem[];
+```
+
+Defined in: [app-hotkeys.ts:480](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L480)
+
+Joins app hotkeys with live registrations, in declaration order.
+Adapters call this with the manager's registration views.
+
+#### Parameters
+
+##### registrations
+
+`Iterable`\<[`HotkeyRegistrationView`](../type-aliases/HotkeyRegistrationView.md)\>
+
+#### Returns
+
+[`AppHotkeyListItem`](../interfaces/AppHotkeyListItem.md)\<`T`\[keyof `T`\]\>[]
+
+***
+
+### resetCustomHotkey()
+
+```ts
+resetCustomHotkey(id): void;
+```
+
+Defined in: [app-hotkeys.ts:457](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L457)
+
+Restores the default hotkey for an app hotkey.
+
+#### Parameters
+
+##### id
+
+keyof `T` & `string`
+
+#### Returns
+
+`void`
+
+***
+
+### resetCustomHotkeys()
+
+```ts
+resetCustomHotkeys(): void;
+```
+
+Defined in: [app-hotkeys.ts:464](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L464)
+
+Restores every default hotkey.
+
+#### Returns
+
+`void`
+
+***
+
+### setAppHotkeys()
+
+```ts
+setAppHotkeys(appHotkeys): void;
+```
+
+Defined in: [app-hotkeys.ts:390](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L390)
+
+Replaces the declarations, for example after hot module replacement.
+Custom hotkeys for ids that still exist are kept.
+
+#### Parameters
+
+##### appHotkeys
+
+`T`
+
+#### Returns
+
+`void`
+
+***
+
+### setCustomHotkey()
+
+```ts
+setCustomHotkey(id, hotkey): AppHotkey[];
+```
+
+Defined in: [app-hotkeys.ts:432](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L432)
+
+Sets the user's hotkey for an app hotkey. `null` unbinds it. A hotkey
+equal to the default removes the customization.
+
+#### Parameters
+
+##### id
+
+keyof `T` & `string`
+
+##### hotkey
+
+[`Hotkey`](../type-aliases/Hotkey.md) \| `null`
+
+#### Returns
+
+[`AppHotkey`](../interfaces/AppHotkey.md)\<`string`,
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null`\>[]
+
+Conflicting app hotkeys. When any exist, nothing changes.
+
+***
+
+### setOptions()
+
+```ts
+setOptions(options): void;
+```
+
+Defined in: [app-hotkeys.ts:382](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L382)
+
+Updates callbacks and other options without resetting custom hotkeys.
+
+#### Parameters
+
+##### options
+
+`Omit`\<[`AppHotkeysStoreOptions`](../interfaces/AppHotkeysStoreOptions.md)\<`T`\>, `"customHotkeys"`\>
+
+#### Returns
+
+`void`
diff --git a/docs/reference/classes/HotkeyManager.md b/docs/reference/classes/HotkeyManager.md
index 23a15316..b05beabb 100644
--- a/docs/reference/classes/HotkeyManager.md
+++ b/docs/reference/classes/HotkeyManager.md
@@ -3,38 +3,63 @@ id: HotkeyManager
title: HotkeyManager
---
-Defined in: [hotkey-manager.ts:191](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L191)
+Defined in: [hotkey-manager.ts:311](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L311)
-Singleton manager for hotkey registrations.
+Singleton manager for hotkey registrations, including sequences.
-This class provides a centralized way to register and manage keyboard hotkeys.
-It uses a single event listener for efficiency, regardless of how many hotkeys
-are registered.
+This class provides a centralized way to register and manage keyboard
+hotkeys. It attaches one keydown and one keyup listener per target,
+regardless of how many hotkeys are registered.
+
+Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
+pressed within the timeout. Modifier-only events (Shift, Control, Alt, or
+Meta alone) neither advance nor reset a sequence, so chained modifier chords
+such as `['Shift+R', 'Shift+T']` work.
## Example
```ts
const manager = HotkeyManager.getInstance()
-const unregister = manager.register('Mod+S', (event, context) => {
+const save = manager.register('Mod+S', (event, context) => {
console.log('Save triggered!')
})
+const top = manager.register(['G', 'G'], () => scrollToTop(), { timeout: 500 })
// Later, to unregister:
-unregister()
+save.unregister()
+top.unregister()
```
## Properties
+### appHotkeys
+
+```ts
+readonly appHotkeys: Store<
+ | AppHotkeysStore>>>
+| null>;
+```
+
+Defined in: [hotkey-manager.ts:340](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L340)
+
+The app hotkeys store published by a framework provider, so tools such as
+devtools can list declared hotkeys that are not registered.
+
+***
+
### registrations
```ts
readonly registrations: Store>;
```
-Defined in: [hotkey-manager.ts:213](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L213)
+Defined in: [hotkey-manager.ts:333](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L333)
-The TanStack Store containing all hotkey registrations.
+The TanStack Store containing all hotkey registrations, chords and sequences.
Use this to subscribe to registration changes or access current registrations.
#### Example
@@ -61,7 +86,7 @@ for (const [id, reg] of manager.registrations.state) {
destroy(): void;
```
-Defined in: [hotkey-manager.ts:796](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L796)
+Defined in: [hotkey-manager.ts:1042](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L1042)
Destroys the manager and removes all listeners.
@@ -77,9 +102,9 @@ Destroys the manager and removes all listeners.
getRegistrationCount(): number;
```
-Defined in: [hotkey-manager.ts:761](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L761)
+Defined in: [hotkey-manager.ts:1012](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L1012)
-Gets the number of registered hotkeys.
+Gets the number of registered hotkeys, chords and sequences.
#### Returns
@@ -93,7 +118,7 @@ Gets the number of registered hotkeys.
isRegistered(hotkey, target?): boolean;
```
-Defined in: [hotkey-manager.ts:772](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L772)
+Defined in: [hotkey-manager.ts:1023](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L1023)
Checks if a specific hotkey is registered.
@@ -101,13 +126,13 @@ Checks if a specific hotkey is registered.
##### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md)
+[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
-The hotkey string to check
+The chord or sequence to check
##### target?
-`Document` \| `Window` \| `HTMLElement`
+[`Target`](../type-aliases/Target.md)
Optional target element to match (if provided, both hotkey and target must match)
@@ -122,26 +147,36 @@ True if a matching registration exists
### register()
```ts
-register(
+register(
hotkey,
callback,
- options?): HotkeyRegistrationHandle;
+options?): HotkeyRegistrationHandle>;
```
-Defined in: [hotkey-manager.ts:276](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L276)
+Defined in: [hotkey-manager.ts:410](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L410)
Registers a hotkey handler and returns a handle for updating the registration.
+Pass a chord (`'Mod+S'` or a RawHotkey object) or a sequence (`['G', 'G']`).
+A one-step sequence registers as its chord. Chords accept `requireReset`;
+sequences accept `timeout`.
+
The returned handle allows updating the callback and options without
re-registering, which is useful for avoiding stale closures in React.
+#### Type Parameters
+
+##### T
+
+`T` *extends* [`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
+
#### Parameters
##### hotkey
-[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
+`T`
-The hotkey string (e.g., 'Mod+S') or RawHotkey object
+A chord string, RawHotkey object, or sequence
##### callback
@@ -151,13 +186,13 @@ The function to call when the hotkey is pressed
##### options?
-[`HotkeyOptions`](../interfaces/HotkeyOptions.md) = `{}`
+[`HotkeyOptionsFor`](../type-aliases/HotkeyOptionsFor.md)\<`T`\>
Options for the hotkey behavior
#### Returns
-[`HotkeyRegistrationHandle`](../interfaces/HotkeyRegistrationHandle.md)
+[`HotkeyRegistrationHandle`](../interfaces/HotkeyRegistrationHandle.md)\<[`HotkeyOptionsFor`](../type-aliases/HotkeyOptionsFor.md)\<`T`\>\>
A handle for managing the registration
@@ -178,16 +213,33 @@ handle.unregister()
***
+### resetSequenceProgress()
+
+```ts
+resetSequenceProgress(): void;
+```
+
+Defined in: [hotkey-manager.ts:957](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L957)
+
+Resets the progress of every in-progress sequence.
+
+#### Returns
+
+`void`
+
+***
+
### triggerRegistration()
```ts
triggerRegistration(id): boolean;
```
-Defined in: [hotkey-manager.ts:723](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L723)
+Defined in: [hotkey-manager.ts:975](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L975)
Triggers a registration's callback programmatically from devtools.
-Creates a synthetic KeyboardEvent and invokes the callback.
+Creates a synthetic KeyboardEvent from the chord (or a sequence's last step)
+and invokes the callback.
#### Parameters
@@ -211,7 +263,7 @@ True if the registration was found and triggered
static getInstance(): HotkeyManager;
```
-Defined in: [hotkey-manager.ts:234](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L234)
+Defined in: [hotkey-manager.ts:359](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L359)
Gets the singleton instance of HotkeyManager.
@@ -227,7 +279,7 @@ Gets the singleton instance of HotkeyManager.
static resetInstance(): void;
```
-Defined in: [hotkey-manager.ts:244](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L244)
+Defined in: [hotkey-manager.ts:369](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L369)
Resets the singleton instance. Useful for testing.
diff --git a/docs/reference/classes/HotkeyRecorder.md b/docs/reference/classes/HotkeyRecorder.md
index bacc0560..9c979847 100644
--- a/docs/reference/classes/HotkeyRecorder.md
+++ b/docs/reference/classes/HotkeyRecorder.md
@@ -3,45 +3,40 @@ id: HotkeyRecorder
title: HotkeyRecorder
---
-Defined in: [hotkey-recorder.ts:94](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L94)
+Defined in: [hotkey-recorder.ts:144](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L144)
Framework-agnostic class for recording keyboard shortcuts.
-This class handles all the complexity of capturing keyboard events,
-converting them to hotkey strings, and handling edge cases like
-Escape to cancel or Backspace/Delete to clear.
+With the default `maxSteps: 1`, the first valid chord commits. With a larger
+`maxSteps`, each chord adds a step; the recording commits on Enter (unless
+`commitKeys: 'none'`), after `idleTimeoutMs`, or when it reaches `maxSteps`.
+Backspace/Delete removes the last step, and on an empty recording calls
+`onClear`. Escape cancels. A one-step result is a chord string.
State Management:
- Uses TanStack Store for reactive state management
- State can be accessed via `recorder.store.state` when using the class directly
-- When using framework adapters (React), use `useSelector` hooks for reactive state
+- When using framework adapters, use the `useHotkeyRecorder` hook for reactive state
## Example
```ts
const recorder = new HotkeyRecorder({
onRecord: (hotkey) => {
- console.log('Recorded:', hotkey)
- },
- onCancel: () => {
- console.log('Recording cancelled')
+ console.log('Recorded:', hotkey) // 'Mod+S'
},
})
-// Start recording
-recorder.start()
-
-// Access state directly
-console.log(recorder.store.state.isRecording) // true
-
-// Subscribe to changes with TanStack Store
-const unsubscribe = recorder.store.subscribe(() => {
- console.log('Recording:', recorder.store.state.isRecording)
+const sequenceRecorder = new HotkeyRecorder({
+ maxSteps: 3,
+ onRecord: (hotkey) => {
+ console.log('Recorded:', hotkey) // 'Mod+S' or ['G', 'H']
+ },
})
-// Cleanup
+recorder.start()
+// ... later
recorder.destroy()
-unsubscribe()
```
## Constructors
@@ -52,16 +47,33 @@ unsubscribe()
new HotkeyRecorder(options): HotkeyRecorder;
```
-Defined in: [hotkey-recorder.ts:119](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L119)
+Defined in: [hotkey-recorder.ts:169](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L169)
+
+#### Parameters
+
+##### options
-Options may be a getter to read current configuration during an active session.
+ \| [`HotkeyChordRecorderOptions`](../interfaces/HotkeyChordRecorderOptions.md)
+ \| (() => [`HotkeyChordRecorderOptions`](../interfaces/HotkeyChordRecorderOptions.md))
+
+#### Returns
+
+`HotkeyRecorder`
+
+### Constructor
+
+```ts
+new HotkeyRecorder(options): HotkeyRecorder;
+```
+
+Defined in: [hotkey-recorder.ts:172](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L172)
#### Parameters
##### options
- \| [`HotkeyRecorderOptions`](../interfaces/HotkeyRecorderOptions.md)
- \| (() => [`HotkeyRecorderOptions`](../interfaces/HotkeyRecorderOptions.md))
+ \| [`HotkeySequenceRecorderOptions`](../interfaces/HotkeySequenceRecorderOptions.md)
+ \| (() => [`HotkeySequenceRecorderOptions`](../interfaces/HotkeySequenceRecorderOptions.md))
#### Returns
@@ -75,10 +87,7 @@ Options may be a getter to read current configuration during an active session.
readonly store: Store;
```
-Defined in: [hotkey-recorder.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L99)
-
-The TanStack Store instance containing the recorder state.
-Use this to subscribe to state changes or access current state.
+Defined in: [hotkey-recorder.ts:145](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L145)
## Methods
@@ -88,7 +97,7 @@ Use this to subscribe to state changes or access current state.
cancel(): void;
```
-Defined in: [hotkey-recorder.ts:302](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L302)
+Defined in: [hotkey-recorder.ts:417](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L417)
Cancel recording without saving.
@@ -101,13 +110,31 @@ the onCancel callback if provided.
***
+### commit()
+
+```ts
+commit(): void;
+```
+
+Defined in: [hotkey-recorder.ts:326](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L326)
+
+Commits the recorded steps after validation and conflict checks.
+Called automatically at `maxSteps`, on Enter, or after `idleTimeoutMs`.
+A rejected commit leaves recording active with its steps intact.
+
+#### Returns
+
+`void`
+
+***
+
### destroy()
```ts
destroy(): void;
```
-Defined in: [hotkey-recorder.ts:348](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L348)
+Defined in: [hotkey-recorder.ts:444](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L444)
Clean up event listeners and reset state.
@@ -126,7 +153,7 @@ all event listeners are properly removed.
setOptions(options): void;
```
-Defined in: [hotkey-recorder.ts:128](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L128)
+Defined in: [hotkey-recorder.ts:185](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L185)
Updates the recorder options, including callbacks.
This allows framework adapters to sync callback changes without recreating the recorder.
@@ -135,7 +162,7 @@ This allows framework adapters to sync callback changes without recreating the r
##### options
-`Partial`\<[`HotkeyRecorderOptions`](../interfaces/HotkeyRecorderOptions.md)\>
+`Partial`\<[`HotkeyRecorderOptions`](../type-aliases/HotkeyRecorderOptions.md)\>
#### Returns
@@ -149,13 +176,12 @@ This allows framework adapters to sync callback changes without recreating the r
start(): void;
```
-Defined in: [hotkey-recorder.ts:139](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L139)
+Defined in: [hotkey-recorder.ts:219](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L219)
Start recording a new hotkey.
Sets up a keydown event listener that captures keyboard events
-and converts them to hotkey strings. Recording continues until
-a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.
+and records chords according to `maxSteps`.
#### Returns
@@ -169,7 +195,7 @@ a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.
stop(): void;
```
-Defined in: [hotkey-recorder.ts:281](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L281)
+Defined in: [hotkey-recorder.ts:407](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L407)
Stop recording (same as cancel, but doesn't call onCancel).
diff --git a/docs/reference/classes/HotkeySequenceRecorder.md b/docs/reference/classes/HotkeySequenceRecorder.md
deleted file mode 100644
index 7b9944dc..00000000
--- a/docs/reference/classes/HotkeySequenceRecorder.md
+++ /dev/null
@@ -1,145 +0,0 @@
----
-id: HotkeySequenceRecorder
-title: HotkeySequenceRecorder
----
-
-Defined in: [hotkey-sequence-recorder.ts:104](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L104)
-
-Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
-
-Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
-when [HotkeySequenceRecorderOptions.commitKeys](../interfaces/HotkeySequenceRecorderOptions.md#commitkeys) is `'enter'` (default), **Escape** to cancel,
-**Backspace/Delete** to remove the last step or clear when empty.
-
-## Constructors
-
-### Constructor
-
-```ts
-new HotkeySequenceRecorder(options): HotkeySequenceRecorder;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:131](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L131)
-
-Options may be a getter to read current configuration during an active session.
-
-#### Parameters
-
-##### options
-
- \| [`HotkeySequenceRecorderOptions`](../interfaces/HotkeySequenceRecorderOptions.md)
- \| (() => [`HotkeySequenceRecorderOptions`](../interfaces/HotkeySequenceRecorderOptions.md))
-
-#### Returns
-
-`HotkeySequenceRecorder`
-
-## Properties
-
-### store
-
-```ts
-readonly store: Store;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:105](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L105)
-
-## Methods
-
-### cancel()
-
-```ts
-cancel(): void;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:379](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L379)
-
-Stops, discards in-progress steps, and notifies onCancel.
-
-#### Returns
-
-`void`
-
-***
-
-### commit()
-
-```ts
-commit(): void;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:302](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L302)
-
-Commit the current steps as a sequence. No-op if fewer than one step.
-
-#### Returns
-
-`void`
-
-***
-
-### destroy()
-
-```ts
-destroy(): void;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:411](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L411)
-
-#### Returns
-
-`void`
-
-***
-
-### setOptions()
-
-```ts
-setOptions(options): void;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:140](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L140)
-
-Merges current callbacks and options without discarding recorded steps.
-
-#### Parameters
-
-##### options
-
-`Partial`\<[`HotkeySequenceRecorderOptions`](../interfaces/HotkeySequenceRecorderOptions.md)\>
-
-#### Returns
-
-`void`
-
-***
-
-### start()
-
-```ts
-start(): void;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:183](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L183)
-
-Starts a fresh recording; repeated starts during an active session are ignored.
-
-#### Returns
-
-`void`
-
-***
-
-### stop()
-
-```ts
-stop(): void;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:363](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L363)
-
-Stops and discards in-progress steps without invoking onCancel.
-
-#### Returns
-
-`void`
diff --git a/docs/reference/classes/SequenceManager.md b/docs/reference/classes/SequenceManager.md
deleted file mode 100644
index b157ccaf..00000000
--- a/docs/reference/classes/SequenceManager.md
+++ /dev/null
@@ -1,167 +0,0 @@
----
-id: SequenceManager
-title: SequenceManager
----
-
-Defined in: [sequence-manager.ts:169](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L169)
-
-## Properties
-
-### registrations
-
-```ts
-readonly registrations: Store>;
-```
-
-Defined in: [sequence-manager.ts:176](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L176)
-
-The TanStack Store containing sequence registration views for devtools.
-Subscribe to this to observe registration changes.
-
-## Methods
-
-### destroy()
-
-```ts
-destroy(): void;
-```
-
-Defined in: [sequence-manager.ts:665](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L665)
-
-Destroys the manager and removes all listeners.
-
-#### Returns
-
-`void`
-
-***
-
-### getRegistrationCount()
-
-```ts
-getRegistrationCount(): number;
-```
-
-Defined in: [sequence-manager.ts:658](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L658)
-
-Gets the number of registered sequences.
-
-#### Returns
-
-`number`
-
-***
-
-### register()
-
-```ts
-register(
- sequence,
- callback,
- options?): SequenceRegistrationHandle;
-```
-
-Defined in: [sequence-manager.ts:228](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L228)
-
-Registers a hotkey sequence handler.
-
-#### Parameters
-
-##### sequence
-
-[`HotkeySequence`](../type-aliases/HotkeySequence.md)
-
-Array of hotkey strings that form the sequence
-
-##### callback
-
-[`HotkeyCallback`](../type-aliases/HotkeyCallback.md)
-
-Function to call when the sequence is completed
-
-##### options?
-
-[`SequenceOptions`](../interfaces/SequenceOptions.md) = `{}`
-
-Options for the sequence behavior
-
-#### Returns
-
-[`SequenceRegistrationHandle`](../interfaces/SequenceRegistrationHandle.md)
-
-A handle to update or unregister the sequence
-
-***
-
-### resetAll()
-
-```ts
-resetAll(): void;
-```
-
-Defined in: [sequence-manager.ts:598](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L598)
-
-Resets all sequence progress.
-
-#### Returns
-
-`void`
-
-***
-
-### triggerSequence()
-
-```ts
-triggerSequence(id): boolean;
-```
-
-Defined in: [sequence-manager.ts:613](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L613)
-
-Triggers a sequence's callback programmatically from devtools.
-Creates a synthetic KeyboardEvent from the last key in the sequence.
-
-#### Parameters
-
-##### id
-
-`string`
-
-The registration ID to trigger
-
-#### Returns
-
-`boolean`
-
-True if the registration was found and triggered
-
-***
-
-### getInstance()
-
-```ts
-static getInstance(): SequenceManager;
-```
-
-Defined in: [sequence-manager.ts:197](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L197)
-
-Gets the singleton instance of SequenceManager.
-
-#### Returns
-
-`SequenceManager`
-
-***
-
-### resetInstance()
-
-```ts
-static resetInstance(): void;
-```
-
-Defined in: [sequence-manager.ts:207](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L207)
-
-Resets the singleton instance. Useful for testing.
-
-#### Returns
-
-`void`
diff --git a/docs/reference/functions/areHotkeysEqual.md b/docs/reference/functions/areHotkeysEqual.md
index e63a32d3..e0a8f415 100644
--- a/docs/reference/functions/areHotkeysEqual.md
+++ b/docs/reference/functions/areHotkeysEqual.md
@@ -10,9 +10,10 @@ function areHotkeysEqual(
platform?): boolean;
```
-Defined in: [match.ts:194](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L194)
+Defined in: [match.ts:203](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L203)
-Compares normalized binding identity, including all four modifiers.
+Compares normalized hotkey identity, including all four modifiers.
+Sequences are equal when every step is equal; a one-step sequence equals its chord.
Aliases resolve on the supplied platform. A physical code and a logical key
remain distinct even when one keyboard event could match both.
diff --git a/docs/reference/functions/assertValidHotkey.md b/docs/reference/functions/assertValidHotkey.md
index 372605cd..40f44c7b 100644
--- a/docs/reference/functions/assertValidHotkey.md
+++ b/docs/reference/functions/assertValidHotkey.md
@@ -7,7 +7,7 @@ title: assertValidHotkey
function assertValidHotkey(hotkey): void;
```
-Defined in: [validate.ts:134](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L134)
+Defined in: [validate.ts:163](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L163)
Validates a hotkey and throws an error if invalid.
Useful for development-time validation.
@@ -16,7 +16,7 @@ Useful for development-time validation.
### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md) \| `string` & `object`
+[`ValidatableHotkey`](../type-aliases/ValidatableHotkey.md)
The hotkey string to validate
diff --git a/docs/reference/functions/checkHotkey.md b/docs/reference/functions/checkHotkey.md
index 7a6d0f15..79cf8d1d 100644
--- a/docs/reference/functions/checkHotkey.md
+++ b/docs/reference/functions/checkHotkey.md
@@ -7,7 +7,7 @@ title: checkHotkey
function checkHotkey(hotkey): boolean;
```
-Defined in: [validate.ts:155](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L155)
+Defined in: [validate.ts:186](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L186)
Validates a hotkey and logs warnings to the console.
Useful for development-time feedback.
@@ -16,7 +16,7 @@ Useful for development-time feedback.
### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md) \| `string` & `object`
+[`ValidatableHotkey`](../type-aliases/ValidatableHotkey.md)
The hotkey string to validate
diff --git a/docs/reference/functions/createHotkeyHandler.md b/docs/reference/functions/createHotkeyHandler.md
index ba00e63c..5d5370b1 100644
--- a/docs/reference/functions/createHotkeyHandler.md
+++ b/docs/reference/functions/createHotkeyHandler.md
@@ -10,7 +10,7 @@ function createHotkeyHandler(
options?): (event) => void;
```
-Defined in: [match.ts:87](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L87)
+Defined in: [match.ts:95](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L95)
Creates a keyboard event handler that calls the callback when the hotkey matches.
@@ -18,7 +18,7 @@ Creates a keyboard event handler that calls the callback when the hotkey matches
### hotkey
- \| [`Hotkey`](../type-aliases/Hotkey.md)
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
\| [`ParsedHotkey`](../type-aliases/ParsedHotkey.md)
The hotkey string or ParsedHotkey to match
diff --git a/docs/reference/functions/createMultiHotkeyHandler.md b/docs/reference/functions/createMultiHotkeyHandler.md
index 6a57ecc7..c64cb432 100644
--- a/docs/reference/functions/createMultiHotkeyHandler.md
+++ b/docs/reference/functions/createMultiHotkeyHandler.md
@@ -7,7 +7,7 @@ title: createMultiHotkeyHandler
function createMultiHotkeyHandler(handlers, options?): (event) => void;
```
-Defined in: [match.ts:138](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L138)
+Defined in: [match.ts:146](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L146)
Creates a handler that matches multiple hotkeys.
diff --git a/docs/reference/functions/createSequenceMatcher.md b/docs/reference/functions/createSequenceMatcher.md
index 13937243..e46cfb8d 100644
--- a/docs/reference/functions/createSequenceMatcher.md
+++ b/docs/reference/functions/createSequenceMatcher.md
@@ -7,7 +7,7 @@ title: createSequenceMatcher
function createSequenceMatcher(sequence, options?): object;
```
-Defined in: [sequence-manager.ts:704](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L704)
+Defined in: [match.ts:259](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L259)
Creates a simple sequence matcher for one-off use.
diff --git a/docs/reference/functions/defineAppHotkeys.md b/docs/reference/functions/defineAppHotkeys.md
new file mode 100644
index 00000000..bd50ac63
--- /dev/null
+++ b/docs/reference/functions/defineAppHotkeys.md
@@ -0,0 +1,40 @@
+---
+id: defineAppHotkeys
+title: defineAppHotkeys
+---
+
+```ts
+function defineAppHotkeys(definitions): DefinedAppHotkeys;
+```
+
+Defined in: [app-hotkeys.ts:175](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L175)
+
+Declares every app hotkey up front, without registering any, so cheat
+sheets and settings screens can list hotkeys whose components have not
+mounted. Pass the result to `HotkeysProvider` as `appHotkeys`.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `Record`\<`string`, [`AppHotkeyInput`](../interfaces/AppHotkeyInput.md)\>
+
+## Parameters
+
+### definitions
+
+`T` & `ValidatedAppHotkeyInputs`\<`T`\>
+
+## Returns
+
+[`DefinedAppHotkeys`](../type-aliases/DefinedAppHotkeys.md)\<`T`\>
+
+## Example
+
+```ts
+export const appHotkeys = defineAppHotkeys({
+ 'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save', group: 'Document' } },
+ 'nav.home': { hotkey: ['G', 'H'], meta: { name: 'Go home' }, options: { timeout: 800 } },
+ 'palette.open': { hotkey: null, meta: { name: 'Command palette' } },
+})
+```
diff --git a/docs/reference/functions/findHotkeyConflicts.md b/docs/reference/functions/findHotkeyConflicts.md
index 46ece2f0..344e532c 100644
--- a/docs/reference/functions/findHotkeyConflicts.md
+++ b/docs/reference/functions/findHotkeyConflicts.md
@@ -17,8 +17,7 @@ discover unmounted handlers, external listeners, or other keyboard layouts.
### candidate
- \| [`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
- \| readonly [`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)[]
+[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
### options?
@@ -26,4 +25,4 @@ discover unmounted handlers, external listeners, or other keyboard layouts.
## Returns
-[`HotkeyConflict`](../type-aliases/HotkeyConflict.md)[]
+[`HotkeyConflict`](../interfaces/HotkeyConflict.md)[]
diff --git a/docs/reference/functions/formatForDisplay.md b/docs/reference/functions/formatForDisplay.md
index 88c1aef8..c05cd3a2 100644
--- a/docs/reference/functions/formatForDisplay.md
+++ b/docs/reference/functions/formatForDisplay.md
@@ -5,11 +5,68 @@ title: formatForDisplay
## Call Signature
+```ts
+function formatForDisplay(hotkey, options): string[][];
+```
+
+Defined in: [format.ts:95](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L95)
+
+Formats a hotkey for display in a user interface.
+
+On macOS, uses symbols (⇧⌘S) in Control, Option, Shift, Command order.
+Display ordering does not change the normalized hotkey used for registration.
+On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
+The separator can be customized with `separatorToken`.
+Physical codes use conventional display labels: `[KeyS]` becomes `S` and
+`[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
+or change matching. Supply a resolved `layoutMap` for layout-aware labels;
+`keyLabels` overrides both layout entries and fallback labels.
+Sequence steps are formatted individually and joined with `sequenceSeparator`
+(a space by default).
+
+### Parameters
+
+#### hotkey
+
+readonly [`DisplayHotkeyChord`](../type-aliases/DisplayHotkeyChord.md)[]
+
+A logical or physical string, raw object, ParsedHotkey, or sequence
+
+#### options
+
+[`FormatDisplayOptions`](../interfaces/FormatDisplayOptions.md) & `object`
+
+Formatting options
+
+### Returns
+
+`string`[][]
+
+Display text, or individual key labels when parts is true (one array per step for sequences)
+
+### Example
+
+```ts
+formatForDisplay('Mod+Shift+S', { platform: 'mac' })
+// Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)
+
+formatForDisplay('Mod+Shift+S', { platform: 'windows' })
+// Returns: 'Ctrl+Shift+S'
+
+formatForDisplay('Escape')
+// Returns: 'Esc' (on all platforms)
+
+formatForDisplay(['G', 'H'])
+// Returns: 'G H'
+```
+
+## Call Signature
+
```ts
function formatForDisplay(hotkey, options): string[];
```
-Defined in: [format.ts:101](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L101)
+Defined in: [format.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L99)
Formats a hotkey for display in a user interface.
@@ -21,14 +78,16 @@ Physical codes use conventional display labels: `[KeyS]` becomes `S` and
`[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
or change matching. Supply a resolved `layoutMap` for layout-aware labels;
`keyLabels` overrides both layout entries and fallback labels.
+Sequence steps are formatted individually and joined with `sequenceSeparator`
+(a space by default).
### Parameters
#### hotkey
-[`DisplayHotkey`](../type-aliases/DisplayHotkey.md)
+[`DisplayHotkeyChord`](../type-aliases/DisplayHotkeyChord.md)
-A logical or physical string, raw binding, or ParsedHotkey
+A logical or physical string, raw object, ParsedHotkey, or sequence
#### options
@@ -40,7 +99,7 @@ Formatting options
`string`[]
-Display text, or individual key labels when parts is true
+Display text, or individual key labels when parts is true (one array per step for sequences)
### Example
@@ -53,6 +112,9 @@ formatForDisplay('Mod+Shift+S', { platform: 'windows' })
formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)
+
+formatForDisplay(['G', 'H'])
+// Returns: 'G H'
```
## Call Signature
@@ -61,7 +123,7 @@ formatForDisplay('Escape')
function formatForDisplay(hotkey, options?): string;
```
-Defined in: [format.ts:105](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L105)
+Defined in: [format.ts:103](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L103)
Formats a hotkey for display in a user interface.
@@ -73,6 +135,8 @@ Physical codes use conventional display labels: `[KeyS]` becomes `S` and
`[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
or change matching. Supply a resolved `layoutMap` for layout-aware labels;
`keyLabels` overrides both layout entries and fallback labels.
+Sequence steps are formatted individually and joined with `sequenceSeparator`
+(a space by default).
### Parameters
@@ -80,7 +144,7 @@ or change matching. Supply a resolved `layoutMap` for layout-aware labels;
[`DisplayHotkey`](../type-aliases/DisplayHotkey.md)
-A logical or physical string, raw binding, or ParsedHotkey
+A logical or physical string, raw object, ParsedHotkey, or sequence
#### options?
@@ -92,7 +156,7 @@ Formatting options
`string`
-Display text, or individual key labels when parts is true
+Display text, or individual key labels when parts is true (one array per step for sequences)
### Example
@@ -105,15 +169,18 @@ formatForDisplay('Mod+Shift+S', { platform: 'windows' })
formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)
+
+formatForDisplay(['G', 'H'])
+// Returns: 'G H'
```
## Call Signature
```ts
-function formatForDisplay(hotkey, options): string | string[];
+function formatForDisplay(hotkey, options): string | string[] | string[][];
```
-Defined in: [format.ts:109](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L109)
+Defined in: [format.ts:107](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L107)
Formats a hotkey for display in a user interface.
@@ -125,6 +192,8 @@ Physical codes use conventional display labels: `[KeyS]` becomes `S` and
`[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
or change matching. Supply a resolved `layoutMap` for layout-aware labels;
`keyLabels` overrides both layout entries and fallback labels.
+Sequence steps are formatted individually and joined with `sequenceSeparator`
+(a space by default).
### Parameters
@@ -132,7 +201,7 @@ or change matching. Supply a resolved `layoutMap` for layout-aware labels;
[`DisplayHotkey`](../type-aliases/DisplayHotkey.md)
-A logical or physical string, raw binding, or ParsedHotkey
+A logical or physical string, raw object, ParsedHotkey, or sequence
#### options
@@ -142,9 +211,9 @@ Formatting options
### Returns
-`string` \| `string`[]
+`string` \| `string`[] \| `string`[][]
-Display text, or individual key labels when parts is true
+Display text, or individual key labels when parts is true (one array per step for sequences)
### Example
@@ -157,4 +226,7 @@ formatForDisplay('Mod+Shift+S', { platform: 'windows' })
formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)
+
+formatForDisplay(['G', 'H'])
+// Returns: 'G H'
```
diff --git a/docs/reference/functions/formatHotkey.md b/docs/reference/functions/formatHotkey.md
index e76c1d3e..0f33fa89 100644
--- a/docs/reference/functions/formatHotkey.md
+++ b/docs/reference/functions/formatHotkey.md
@@ -7,7 +7,7 @@ title: formatHotkey
function formatHotkey(parsed): string;
```
-Defined in: [format.ts:54](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L54)
+Defined in: [format.ts:37](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L37)
Converts a ParsedHotkey back to a hotkey string.
diff --git a/docs/reference/functions/formatHotkeySequence.md b/docs/reference/functions/formatHotkeySequence.md
deleted file mode 100644
index cafc3383..00000000
--- a/docs/reference/functions/formatHotkeySequence.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-id: formatHotkeySequence
-title: formatHotkeySequence
----
-
-```ts
-function formatHotkeySequence(sequence): string;
-```
-
-Defined in: [format.ts:38](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L38)
-
-Joins stored sequence steps with spaces, preserving physical code tokens.
-For user-facing labels, call formatForDisplay on each step instead.
-
-## Parameters
-
-### sequence
-
-[`Hotkey`](../type-aliases/Hotkey.md)[]
-
-Array of hotkey strings that form the sequence
-
-## Returns
-
-`string`
-
-A space-separated string (e.g. ['G','G'] → 'G G')
-
-## Example
-
-```ts
-formatHotkeySequence(['G', 'G']) // 'G G'
-formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
-```
diff --git a/docs/reference/functions/formatWithLabels.md b/docs/reference/functions/formatWithLabels.md
deleted file mode 100644
index 9e76b4fc..00000000
--- a/docs/reference/functions/formatWithLabels.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-id: formatWithLabels
-title: formatWithLabels
----
-
-```ts
-function formatWithLabels(hotkey, options?): string;
-```
-
-Defined in: [format.ts:185](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L185)
-
-## Parameters
-
-### hotkey
-
-[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
-
-### options?
-
-`Omit`\<[`FormatDisplayOptions`](../interfaces/FormatDisplayOptions.md), `"useSymbols"` \| `"parts"`\> = `{}`
-
-## Returns
-
-`string`
-
-## Deprecated
-
-Use [formatForDisplay](formatForDisplay.md) instead with `useSymbols: false` option.
diff --git a/docs/reference/functions/getAppHotkeyRegistrationOptions.md b/docs/reference/functions/getAppHotkeyRegistrationOptions.md
new file mode 100644
index 00000000..6c8e6cb3
--- /dev/null
+++ b/docs/reference/functions/getAppHotkeyRegistrationOptions.md
@@ -0,0 +1,24 @@
+---
+id: getAppHotkeyRegistrationOptions
+title: getAppHotkeyRegistrationOptions
+---
+
+```ts
+function getAppHotkeyRegistrationOptions(appHotkey): AppHotkeyChordOptions & AppHotkeySequenceOptions & object;
+```
+
+Defined in: [app-hotkeys.ts:528](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L528)
+
+Options that adapters pass to the manager when registering an app hotkey:
+declared options, meta, and the app hotkey id. The manager drops options
+that do not apply to the effective hotkey's kind.
+
+## Parameters
+
+### appHotkey
+
+[`AppHotkey`](../interfaces/AppHotkey.md)
+
+## Returns
+
+[`AppHotkeyChordOptions`](../type-aliases/AppHotkeyChordOptions.md) & [`AppHotkeySequenceOptions`](../type-aliases/AppHotkeySequenceOptions.md) & `object`
diff --git a/docs/reference/functions/getHotkeyManager.md b/docs/reference/functions/getHotkeyManager.md
index 722451ae..4eda621b 100644
--- a/docs/reference/functions/getHotkeyManager.md
+++ b/docs/reference/functions/getHotkeyManager.md
@@ -7,7 +7,7 @@ title: getHotkeyManager
function getHotkeyManager(): HotkeyManager;
```
-Defined in: [hotkey-manager.ts:812](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L812)
+Defined in: [hotkey-manager.ts:1059](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L1059)
Gets the singleton HotkeyManager instance.
Convenience function for accessing the manager.
diff --git a/docs/reference/functions/getSequenceManager.md b/docs/reference/functions/getSequenceManager.md
deleted file mode 100644
index 78ca51b9..00000000
--- a/docs/reference/functions/getSequenceManager.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-id: getSequenceManager
-title: getSequenceManager
----
-
-```ts
-function getSequenceManager(): SequenceManager;
-```
-
-Defined in: [sequence-manager.ts:678](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L678)
-
-Gets the singleton SequenceManager instance.
-Convenience function for accessing the manager.
-
-## Returns
-
-[`SequenceManager`](../classes/SequenceManager.md)
diff --git a/docs/reference/functions/hasNonModifierKey.md b/docs/reference/functions/hasNonModifierKey.md
index 94197a1b..5d904583 100644
--- a/docs/reference/functions/hasNonModifierKey.md
+++ b/docs/reference/functions/hasNonModifierKey.md
@@ -7,7 +7,7 @@ title: hasNonModifierKey
function hasNonModifierKey(hotkey, platform?): boolean;
```
-Defined in: [parse.ts:336](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L336)
+Defined in: [parse.ts:373](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L373)
Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
@@ -18,7 +18,7 @@ just a combination of modifiers without an action key.
### hotkey
- \| [`Hotkey`](../type-aliases/Hotkey.md)
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
\| `string` & `object`
\| [`ParsedHotkey`](../type-aliases/ParsedHotkey.md)
diff --git a/docs/reference/functions/isAppHotkey.md b/docs/reference/functions/isAppHotkey.md
new file mode 100644
index 00000000..b5291170
--- /dev/null
+++ b/docs/reference/functions/isAppHotkey.md
@@ -0,0 +1,22 @@
+---
+id: isAppHotkey
+title: isAppHotkey
+---
+
+```ts
+function isAppHotkey(value): value is AppHotkey;
+```
+
+Defined in: [app-hotkeys.ts:195](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L195)
+
+Whether a value is an app hotkey created by `defineAppHotkeys`.
+
+## Parameters
+
+### value
+
+`unknown`
+
+## Returns
+
+value is AppHotkey\
diff --git a/docs/reference/functions/isCustomHotkey.md b/docs/reference/functions/isCustomHotkey.md
new file mode 100644
index 00000000..75446925
--- /dev/null
+++ b/docs/reference/functions/isCustomHotkey.md
@@ -0,0 +1,26 @@
+---
+id: isCustomHotkey
+title: isCustomHotkey
+---
+
+```ts
+function isCustomHotkey(appHotkey, platform?): boolean;
+```
+
+Defined in: [app-hotkeys.ts:213](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L213)
+
+Whether an app hotkey's effective hotkey differs from its default.
+
+## Parameters
+
+### appHotkey
+
+[`AppHotkey`](../interfaces/AppHotkey.md)
+
+### platform?
+
+`Platform` = `...`
+
+## Returns
+
+`boolean`
diff --git a/docs/reference/functions/isHotkeySequence.md b/docs/reference/functions/isHotkeySequence.md
new file mode 100644
index 00000000..79619c46
--- /dev/null
+++ b/docs/reference/functions/isHotkeySequence.md
@@ -0,0 +1,23 @@
+---
+id: isHotkeySequence
+title: isHotkeySequence
+---
+
+```ts
+function isHotkeySequence(hotkey): hotkey is HotkeySequence;
+```
+
+Defined in: [parse.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L23)
+
+Whether a hotkey is a sequence. Use this instead of `Array.isArray`, which
+does not narrow readonly arrays.
+
+## Parameters
+
+### hotkey
+
+[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
+
+## Returns
+
+`hotkey is HotkeySequence`
diff --git a/docs/reference/functions/isModifierKey.md b/docs/reference/functions/isModifierKey.md
index c7c49d7b..f7cdd584 100644
--- a/docs/reference/functions/isModifierKey.md
+++ b/docs/reference/functions/isModifierKey.md
@@ -7,7 +7,7 @@ title: isModifierKey
function isModifierKey(key): key is string;
```
-Defined in: [parse.ts:250](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L250)
+Defined in: [parse.ts:287](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L287)
Checks if a string is a recognized modifier token (including aliases).
diff --git a/docs/reference/functions/matchesHeldModifiers.md b/docs/reference/functions/matchesHeldModifiers.md
index de844b2e..4f016e87 100644
--- a/docs/reference/functions/matchesHeldModifiers.md
+++ b/docs/reference/functions/matchesHeldModifiers.md
@@ -10,12 +10,13 @@ function matchesHeldModifiers(
options?): boolean;
```
-Defined in: [hint.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hint.ts#L23)
+Defined in: [hint.ts:24](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hint.ts#L24)
Returns whether held modifiers should reveal a shortcut hint.
By default, any nonempty subset of the binding's modifiers qualifies; an
unrelated modifier hides the hint. `exact` requires every binding modifier.
Nonmodifier keys are ignored. This does not check registration or focus.
+A sequence reveals its hint from its first step.
## Parameters
diff --git a/docs/reference/functions/matchesKeyboardEvent.md b/docs/reference/functions/matchesKeyboardEvent.md
index da398c24..aa013f48 100644
--- a/docs/reference/functions/matchesKeyboardEvent.md
+++ b/docs/reference/functions/matchesKeyboardEvent.md
@@ -10,7 +10,7 @@ function matchesKeyboardEvent(
platform?): boolean;
```
-Defined in: [match.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L49)
+Defined in: [match.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L57)
Checks if a KeyboardEvent matches a hotkey.
@@ -35,7 +35,7 @@ The KeyboardEvent to check
### hotkey
- \| [`Hotkey`](../type-aliases/Hotkey.md)
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
\| [`ParsedHotkey`](../type-aliases/ParsedHotkey.md)
The hotkey string or ParsedHotkey to match against
diff --git a/docs/reference/functions/normalizeHotkey.md b/docs/reference/functions/normalizeHotkey.md
index 4de4410a..c8dd748e 100644
--- a/docs/reference/functions/normalizeHotkey.md
+++ b/docs/reference/functions/normalizeHotkey.md
@@ -4,10 +4,10 @@ title: normalizeHotkey
---
```ts
-function normalizeHotkey(hotkey, platform?): Hotkey;
+function normalizeHotkey(hotkey, platform?): HotkeyChord;
```
-Defined in: [parse.ts:205](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L205)
+Defined in: [parse.ts:229](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L229)
Normalizes a hotkey string to its canonical form.
@@ -33,7 +33,7 @@ The target platform for resolving `Mod` (defaults to auto-detection)
## Returns
-[`Hotkey`](../type-aliases/Hotkey.md)
+[`HotkeyChord`](../type-aliases/HotkeyChord.md)
The normalized hotkey string
diff --git a/docs/reference/functions/normalizeHotkeyFromEvent.md b/docs/reference/functions/normalizeHotkeyFromEvent.md
index c10afff5..f7768cc6 100644
--- a/docs/reference/functions/normalizeHotkeyFromEvent.md
+++ b/docs/reference/functions/normalizeHotkeyFromEvent.md
@@ -4,10 +4,10 @@ title: normalizeHotkeyFromEvent
---
```ts
-function normalizeHotkeyFromEvent(event, platform?): Hotkey;
+function normalizeHotkeyFromEvent(event, platform?): HotkeyChord;
```
-Defined in: [parse.ts:309](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L309)
+Defined in: [parse.ts:346](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L346)
Normalizes a keyboard event to the same canonical hotkey string as [normalizeHotkey](normalizeHotkey.md).
@@ -27,4 +27,4 @@ Target platform for `Mod` eligibility
## Returns
-[`Hotkey`](../type-aliases/Hotkey.md)
+[`HotkeyChord`](../type-aliases/HotkeyChord.md)
diff --git a/docs/reference/functions/normalizeHotkeyFromParsed.md b/docs/reference/functions/normalizeHotkeyFromParsed.md
index 55d4551c..8a58660e 100644
--- a/docs/reference/functions/normalizeHotkeyFromParsed.md
+++ b/docs/reference/functions/normalizeHotkeyFromParsed.md
@@ -4,10 +4,10 @@ title: normalizeHotkeyFromParsed
---
```ts
-function normalizeHotkeyFromParsed(parsed, platform?): Hotkey;
+function normalizeHotkeyFromParsed(parsed, platform?): HotkeyChord;
```
-Defined in: [parse.ts:218](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L218)
+Defined in: [parse.ts:242](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L242)
Same canonical string as [normalizeHotkey](normalizeHotkey.md), but from an already-parsed hotkey.
@@ -23,4 +23,4 @@ Same canonical string as [normalizeHotkey](normalizeHotkey.md), but from an alre
## Returns
-[`Hotkey`](../type-aliases/Hotkey.md)
+[`HotkeyChord`](../type-aliases/HotkeyChord.md)
diff --git a/docs/reference/functions/normalizeRegisterableHotkey.md b/docs/reference/functions/normalizeRegisterableHotkey.md
index 44338ec7..c70df2dd 100644
--- a/docs/reference/functions/normalizeRegisterableHotkey.md
+++ b/docs/reference/functions/normalizeRegisterableHotkey.md
@@ -3,25 +3,54 @@ id: normalizeRegisterableHotkey
title: normalizeRegisterableHotkey
---
+## Call Signature
+
+```ts
+function normalizeRegisterableHotkey(hotkey, platform?): HotkeyChord;
+```
+
+Defined in: [parse.ts:254](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L254)
+
+Normalizes a chord (string or [RawHotkey](../type-aliases/RawHotkey.md) object) or a sequence to canonical form.
+Each sequence step is normalized, and a one-step sequence becomes its chord.
+Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+
+### Parameters
+
+#### hotkey
+
+[`RegisterableHotkeyChord`](../type-aliases/RegisterableHotkeyChord.md)
+
+#### platform?
+
+`"mac"` \| `"windows"` \| `"linux"`
+
+### Returns
+
+[`HotkeyChord`](../type-aliases/HotkeyChord.md)
+
+## Call Signature
+
```ts
function normalizeRegisterableHotkey(hotkey, platform?): Hotkey;
```
-Defined in: [parse.ts:229](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L229)
+Defined in: [parse.ts:258](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L258)
-Normalizes a string or [RawHotkey](../type-aliases/RawHotkey.md) object to the same canonical hotkey string.
+Normalizes a chord (string or [RawHotkey](../type-aliases/RawHotkey.md) object) or a sequence to canonical form.
+Each sequence step is normalized, and a one-step sequence becomes its chord.
Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
-## Parameters
+### Parameters
-### hotkey
+#### hotkey
[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
-### platform?
+#### platform?
`"mac"` \| `"windows"` \| `"linux"`
-## Returns
+### Returns
[`Hotkey`](../type-aliases/Hotkey.md)
diff --git a/docs/reference/functions/parseHotkey.md b/docs/reference/functions/parseHotkey.md
index ffdee9e7..005eb739 100644
--- a/docs/reference/functions/parseHotkey.md
+++ b/docs/reference/functions/parseHotkey.md
@@ -7,7 +7,7 @@ title: parseHotkey
function parseHotkey(hotkey, platform?): ParsedHotkey;
```
-Defined in: [parse.ts:30](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L30)
+Defined in: [parse.ts:54](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L54)
Parses a hotkey string into its component parts.
@@ -15,7 +15,7 @@ Parses a hotkey string into its component parts.
### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md) \| `string` & `object`
+[`HotkeyChord`](../type-aliases/HotkeyChord.md) \| `string` & `object`
The hotkey string to parse (e.g., 'Mod+Shift+S')
diff --git a/docs/reference/functions/parseKeyboardEvent.md b/docs/reference/functions/parseKeyboardEvent.md
index d407d384..167f0870 100644
--- a/docs/reference/functions/parseKeyboardEvent.md
+++ b/docs/reference/functions/parseKeyboardEvent.md
@@ -7,7 +7,7 @@ title: parseKeyboardEvent
function parseKeyboardEvent(event, platform?): ParsedHotkey;
```
-Defined in: [parse.ts:274](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L274)
+Defined in: [parse.ts:311](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L311)
Parses a KeyboardEvent into a ParsedHotkey object.
diff --git a/docs/reference/functions/parseRegisterableHotkey.md b/docs/reference/functions/parseRegisterableHotkey.md
index 1ce0eb12..5109735b 100644
--- a/docs/reference/functions/parseRegisterableHotkey.md
+++ b/docs/reference/functions/parseRegisterableHotkey.md
@@ -7,7 +7,7 @@ title: parseRegisterableHotkey
function parseRegisterableHotkey(hotkey, platform?): ParsedHotkey;
```
-Defined in: [parse.ts:362](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L362)
+Defined in: [parse.ts:399](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L399)
Parses a string or raw binding, resolving Mod for the supplied platform.
Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
@@ -16,7 +16,7 @@ Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
### hotkey
-[`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
+[`RegisterableHotkeyChord`](../type-aliases/RegisterableHotkeyChord.md)
### platform?
diff --git a/docs/reference/functions/provideAppHotkeys.md b/docs/reference/functions/provideAppHotkeys.md
new file mode 100644
index 00000000..b99045c9
--- /dev/null
+++ b/docs/reference/functions/provideAppHotkeys.md
@@ -0,0 +1,65 @@
+---
+id: provideAppHotkeys
+title: provideAppHotkeys
+---
+
+```ts
+function provideAppHotkeys(appHotkeys, options?): object;
+```
+
+Defined in: [app-hotkeys.ts:569](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L569)
+
+Creates an app hotkeys store and publishes it on the HotkeyManager, for
+adapters without a provider component (such as Lit and Alpine). Hotkey
+APIs in those adapters resolve app hotkeys and custom hotkeys from the
+published store. Call it once at startup. Returns the store and a function
+that unpublishes it.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `Readonly`\<`Record`\<`string`, [`AppHotkey`](../interfaces/AppHotkey.md)\<`string`,
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null`\>\>\>
+
+## Parameters
+
+### appHotkeys
+
+`T`
+
+### options?
+
+[`AppHotkeysStoreOptions`](../interfaces/AppHotkeysStoreOptions.md)\<`T`\> = `{}`
+
+## Returns
+
+`object`
+
+### dispose
+
+```ts
+dispose: () => void;
+```
+
+#### Returns
+
+`void`
+
+### store
+
+```ts
+store: AppHotkeysStore;
+```
+
+## Example
+
+```ts
+provideAppHotkeys(appHotkeys, {
+ customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ onCustomHotkeysChange: (custom) =>
+ localStorage.setItem('hotkeys', JSON.stringify(custom)),
+})
+```
diff --git a/docs/reference/functions/publishAppHotkeysStore.md b/docs/reference/functions/publishAppHotkeysStore.md
new file mode 100644
index 00000000..51a06269
--- /dev/null
+++ b/docs/reference/functions/publishAppHotkeysStore.md
@@ -0,0 +1,24 @@
+---
+id: publishAppHotkeysStore
+title: publishAppHotkeysStore
+---
+
+```ts
+function publishAppHotkeysStore(store): () => void;
+```
+
+Defined in: [app-hotkeys.ts:543](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L543)
+
+Publishes a provider's store on the HotkeyManager so devtools can list
+declared hotkeys. Returns a cleanup function that unpublishes it if it is
+still the published store.
+
+## Parameters
+
+### store
+
+[`AppHotkeysStore`](../classes/AppHotkeysStore.md)
+
+## Returns
+
+() => `void`
diff --git a/docs/reference/functions/rawHotkeyToParsedHotkey.md b/docs/reference/functions/rawHotkeyToParsedHotkey.md
index d070c009..b68d8489 100644
--- a/docs/reference/functions/rawHotkeyToParsedHotkey.md
+++ b/docs/reference/functions/rawHotkeyToParsedHotkey.md
@@ -7,7 +7,7 @@ title: rawHotkeyToParsedHotkey
function rawHotkeyToParsedHotkey(raw, platform?): ParsedHotkey;
```
-Defined in: [parse.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L99)
+Defined in: [parse.ts:123](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L123)
Converts a RawHotkey object to a ParsedHotkey.
Optional modifier booleans default to false; modifiers array is derived from them.
diff --git a/docs/reference/functions/resolveAppHotkey.md b/docs/reference/functions/resolveAppHotkey.md
new file mode 100644
index 00000000..782c1544
--- /dev/null
+++ b/docs/reference/functions/resolveAppHotkey.md
@@ -0,0 +1,33 @@
+---
+id: resolveAppHotkey
+title: resolveAppHotkey
+---
+
+```ts
+function resolveAppHotkey(appHotkey, store): AppHotkey;
+```
+
+Defined in: [app-hotkeys.ts:516](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L516)
+
+Returns the provider's version of an app hotkey, so custom hotkeys apply
+even when a component imports the declaration directly. Falls back to the
+given app hotkey when no store declares it.
+
+## Parameters
+
+### appHotkey
+
+[`AppHotkey`](../interfaces/AppHotkey.md)
+
+### store
+
+ \| [`AppHotkeysStore`](../classes/AppHotkeysStore.md)\<`Readonly`\<`Record`\<`string`, [`AppHotkey`](../interfaces/AppHotkey.md)\<`string`,
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null`\>\>\>\>
+ \| `null`
+ \| `undefined`
+
+## Returns
+
+[`AppHotkey`](../interfaces/AppHotkey.md)
diff --git a/docs/reference/functions/simplifyHotkey.md b/docs/reference/functions/simplifyHotkey.md
new file mode 100644
index 00000000..5588bb31
--- /dev/null
+++ b/docs/reference/functions/simplifyHotkey.md
@@ -0,0 +1,29 @@
+---
+id: simplifyHotkey
+title: simplifyHotkey
+---
+
+```ts
+function simplifyHotkey(hotkey): T extends HotkeySequence ? Hotkey : T;
+```
+
+Defined in: [parse.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L33)
+
+Collapses a one-step sequence to its chord without otherwise changing the hotkey.
+Registration APIs treat `['Mod+S']` exactly like `'Mod+S'`.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`RegisterableHotkey`](../type-aliases/RegisterableHotkey.md)
+
+## Parameters
+
+### hotkey
+
+`T`
+
+## Returns
+
+`T` *extends* [`HotkeySequence`](../type-aliases/HotkeySequence.md) ? [`Hotkey`](../type-aliases/Hotkey.md) : `T`
diff --git a/docs/reference/functions/toHotkeyRegistrationView.md b/docs/reference/functions/toHotkeyRegistrationView.md
index ea7cb501..375c020d 100644
--- a/docs/reference/functions/toHotkeyRegistrationView.md
+++ b/docs/reference/functions/toHotkeyRegistrationView.md
@@ -7,17 +7,16 @@ title: toHotkeyRegistrationView
function toHotkeyRegistrationView(reg): HotkeyRegistrationView;
```
-Defined in: [hotkey-manager.ts:107](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L107)
+Defined in: [hotkey-manager.ts:170](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L170)
-Creates a public view from an internal registration,
-stripping the callback function.
+Creates a public view from an internal registration, stripping the callback.
## Parameters
### reg
-[`HotkeyRegistration`](../interfaces/HotkeyRegistration.md)
+[`HotkeyRegistration`](../type-aliases/HotkeyRegistration.md)
## Returns
-[`HotkeyRegistrationView`](../interfaces/HotkeyRegistrationView.md)
+[`HotkeyRegistrationView`](../type-aliases/HotkeyRegistrationView.md)
diff --git a/docs/reference/functions/validateHotkey.md b/docs/reference/functions/validateHotkey.md
index d7c5effc..bdb19da4 100644
--- a/docs/reference/functions/validateHotkey.md
+++ b/docs/reference/functions/validateHotkey.md
@@ -7,9 +7,10 @@ title: validateHotkey
function validateHotkey(hotkey): ValidationResult;
```
-Defined in: [validate.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L25)
+Defined in: [validate.ts:32](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L32)
-Validates a hotkey string and returns any warnings or errors.
+Validates a hotkey and returns any warnings or errors.
+Sequences are validated step by step, and messages name the failing step.
Checks for:
- Valid syntax (modifier+...+key format)
@@ -20,7 +21,7 @@ Checks for:
### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md) \| `string` & `object`
+[`ValidatableHotkey`](../type-aliases/ValidatableHotkey.md)
The hotkey string to validate
@@ -38,4 +39,7 @@ validateHotkey('Mod+S')
validateHotkey('')
// { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+
+validateHotkey(['G', 'Foo+H'])
+// { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
```
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 630487b0..e57e87c6 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -5,30 +5,37 @@ title: "@tanstack/hotkeys"
## Classes
+- [AppHotkeysStore](classes/AppHotkeysStore.md)
- [HotkeyManager](classes/HotkeyManager.md)
- [HotkeyRecorder](classes/HotkeyRecorder.md)
-- [HotkeySequenceRecorder](classes/HotkeySequenceRecorder.md)
- [KeyStateTracker](classes/KeyStateTracker.md)
-- [SequenceManager](classes/SequenceManager.md)
## Interfaces
+- [AppHotkey](interfaces/AppHotkey.md)
+- [AppHotkeyInput](interfaces/AppHotkeyInput.md)
+- [AppHotkeyListItem](interfaces/AppHotkeyListItem.md)
+- [AppHotkeysState](interfaces/AppHotkeysState.md)
+- [AppHotkeysStoreOptions](interfaces/AppHotkeysStoreOptions.md)
- [CreateHotkeyHandlerOptions](interfaces/CreateHotkeyHandlerOptions.md)
- [FormatDisplayOptions](interfaces/FormatDisplayOptions.md)
- [HeldModifierOptions](interfaces/HeldModifierOptions.md)
- [HotkeyCallbackContext](interfaces/HotkeyCallbackContext.md)
+- [HotkeyChordOptions](interfaces/HotkeyChordOptions.md)
+- [HotkeyChordRecorderOptions](interfaces/HotkeyChordRecorderOptions.md)
+- [HotkeyChordRegistration](interfaces/HotkeyChordRegistration.md)
+- [HotkeyChordRegistrationView](interfaces/HotkeyChordRegistrationView.md)
+- [HotkeyConflict](interfaces/HotkeyConflict.md)
- [HotkeyConflictOptions](interfaces/HotkeyConflictOptions.md)
- [HotkeyMeta](interfaces/HotkeyMeta.md)
- [HotkeyOptions](interfaces/HotkeyOptions.md)
-- [HotkeyRecorderOptions](interfaces/HotkeyRecorderOptions.md)
- [HotkeyRecorderState](interfaces/HotkeyRecorderState.md)
- [HotkeyRecorderValidationContext](interfaces/HotkeyRecorderValidationContext.md)
-- [HotkeyRegistration](interfaces/HotkeyRegistration.md)
- [HotkeyRegistrationHandle](interfaces/HotkeyRegistrationHandle.md)
-- [HotkeyRegistrationView](interfaces/HotkeyRegistrationView.md)
+- [HotkeySequenceOptions](interfaces/HotkeySequenceOptions.md)
- [HotkeySequenceRecorderOptions](interfaces/HotkeySequenceRecorderOptions.md)
-- [HotkeySequenceRecorderState](interfaces/HotkeySequenceRecorderState.md)
-- [HotkeySequenceRecorderValidationContext](interfaces/HotkeySequenceRecorderValidationContext.md)
+- [HotkeySequenceRegistration](interfaces/HotkeySequenceRegistration.md)
+- [HotkeySequenceRegistrationView](interfaces/HotkeySequenceRegistrationView.md)
- [KeyboardEventMatch](interfaces/KeyboardEventMatch.md)
- [KeyStateTrackerState](interfaces/KeyStateTrackerState.md)
- [NormalizedKeyboardEvent](interfaces/NormalizedKeyboardEvent.md)
@@ -36,25 +43,36 @@ title: "@tanstack/hotkeys"
- [RawModifiers](interfaces/RawModifiers.md)
- [RecorderOptions](interfaces/RecorderOptions.md)
- [RecorderRejection](interfaces/RecorderRejection.md)
-- [SequenceOptions](interfaces/SequenceOptions.md)
-- [SequenceRegistration](interfaces/SequenceRegistration.md)
-- [SequenceRegistrationHandle](interfaces/SequenceRegistrationHandle.md)
-- [SequenceRegistrationView](interfaces/SequenceRegistrationView.md)
+- [Register](interfaces/Register.md)
- [ValidationResult](interfaces/ValidationResult.md)
## Type Aliases
+- [AppHotkeyChordOptions](type-aliases/AppHotkeyChordOptions.md)
+- [AppHotkeyDefaultKind](type-aliases/AppHotkeyDefaultKind.md)
+- [AppHotkeyId](type-aliases/AppHotkeyId.md)
+- [AppHotkeyOptions](type-aliases/AppHotkeyOptions.md)
+- [AppHotkeys](type-aliases/AppHotkeys.md)
+- [AppHotkeySequenceOptions](type-aliases/AppHotkeySequenceOptions.md)
+- [AppHotkeyStatus](type-aliases/AppHotkeyStatus.md)
- [CanonicalModifier](type-aliases/CanonicalModifier.md)
- [ConflictBehavior](type-aliases/ConflictBehavior.md)
+- [CustomHotkeys](type-aliases/CustomHotkeys.md)
+- [DefinedAppHotkeys](type-aliases/DefinedAppHotkeys.md)
- [DisplayHotkey](type-aliases/DisplayHotkey.md)
+- [DisplayHotkeyChord](type-aliases/DisplayHotkeyChord.md)
- [EditingKey](type-aliases/EditingKey.md)
- [FourModifierHotkey](type-aliases/FourModifierHotkey.md)
- [FunctionKey](type-aliases/FunctionKey.md)
- [Hotkey](type-aliases/Hotkey.md)
- [HotkeyCallback](type-aliases/HotkeyCallback.md)
-- [HotkeyConflict](type-aliases/HotkeyConflict.md)
+- [HotkeyChord](type-aliases/HotkeyChord.md)
+- [HotkeyOptionsFor](type-aliases/HotkeyOptionsFor.md)
+- [HotkeyRecorderCommitKeys](type-aliases/HotkeyRecorderCommitKeys.md)
+- [HotkeyRecorderOptions](type-aliases/HotkeyRecorderOptions.md)
+- [HotkeyRegistration](type-aliases/HotkeyRegistration.md)
+- [HotkeyRegistrationView](type-aliases/HotkeyRegistrationView.md)
- [HotkeySequence](type-aliases/HotkeySequence.md)
-- [HotkeySequenceRecorderCommitKeys](type-aliases/HotkeySequenceRecorderCommitKeys.md)
- [IndividualKey](type-aliases/IndividualKey.md)
- [Key](type-aliases/Key.md)
- [LetterKey](type-aliases/LetterKey.md)
@@ -72,10 +90,13 @@ title: "@tanstack/hotkeys"
- [RawHotkey](type-aliases/RawHotkey.md)
- [RecorderKeyMode](type-aliases/RecorderKeyMode.md)
- [RegisterableHotkey](type-aliases/RegisterableHotkey.md)
+- [RegisterableHotkeyChord](type-aliases/RegisterableHotkeyChord.md)
+- [RegisteredAppHotkeys](type-aliases/RegisteredAppHotkeys.md)
- [SingleModifierHotkey](type-aliases/SingleModifierHotkey.md)
- [Target](type-aliases/Target.md)
- [ThreeModifierHotkey](type-aliases/ThreeModifierHotkey.md)
- [TwoModifierHotkey](type-aliases/TwoModifierHotkey.md)
+- [ValidatableHotkey](type-aliases/ValidatableHotkey.md)
## Variables
@@ -106,16 +127,18 @@ title: "@tanstack/hotkeys"
- [createHotkeyHandler](functions/createHotkeyHandler.md)
- [createMultiHotkeyHandler](functions/createMultiHotkeyHandler.md)
- [createSequenceMatcher](functions/createSequenceMatcher.md)
+- [defineAppHotkeys](functions/defineAppHotkeys.md)
- [detectPlatform](functions/detectPlatform.md)
- [findHotkeyConflicts](functions/findHotkeyConflicts.md)
- [formatForDisplay](functions/formatForDisplay.md)
- [formatHotkey](functions/formatHotkey.md)
-- [formatHotkeySequence](functions/formatHotkeySequence.md)
-- [~~formatWithLabels~~](functions/formatWithLabels.md)
+- [getAppHotkeyRegistrationOptions](functions/getAppHotkeyRegistrationOptions.md)
- [getHotkeyManager](functions/getHotkeyManager.md)
- [getKeyStateTracker](functions/getKeyStateTracker.md)
-- [getSequenceManager](functions/getSequenceManager.md)
- [hasNonModifierKey](functions/hasNonModifierKey.md)
+- [isAppHotkey](functions/isAppHotkey.md)
+- [isCustomHotkey](functions/isCustomHotkey.md)
+- [isHotkeySequence](functions/isHotkeySequence.md)
- [isModifierKey](functions/isModifierKey.md)
- [isSingleLetterKey](functions/isSingleLetterKey.md)
- [matchesHeldModifiers](functions/matchesHeldModifiers.md)
@@ -128,7 +151,11 @@ title: "@tanstack/hotkeys"
- [parseHotkey](functions/parseHotkey.md)
- [parseKeyboardEvent](functions/parseKeyboardEvent.md)
- [parseRegisterableHotkey](functions/parseRegisterableHotkey.md)
+- [provideAppHotkeys](functions/provideAppHotkeys.md)
+- [publishAppHotkeysStore](functions/publishAppHotkeysStore.md)
- [rawHotkeyToParsedHotkey](functions/rawHotkeyToParsedHotkey.md)
+- [resolveAppHotkey](functions/resolveAppHotkey.md)
- [resolveModifier](functions/resolveModifier.md)
+- [simplifyHotkey](functions/simplifyHotkey.md)
- [toHotkeyRegistrationView](functions/toHotkeyRegistrationView.md)
- [validateHotkey](functions/validateHotkey.md)
diff --git a/docs/reference/interfaces/AppHotkey.md b/docs/reference/interfaces/AppHotkey.md
new file mode 100644
index 00000000..7295a7ef
--- /dev/null
+++ b/docs/reference/interfaces/AppHotkey.md
@@ -0,0 +1,106 @@
+---
+id: AppHotkey
+title: AppHotkey
+---
+
+Defined in: [app-hotkeys.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L69)
+
+A declared app hotkey. It never holds a callback: register it with
+`useHotkey(appHotkey, callback)` or the equivalent adapter API.
+
+`TDefault` is the kind of the declared default (`HotkeyChord`,
+`HotkeySequence`, or `null`). Adapters use it to type kind-specific options.
+
+## Type Parameters
+
+### TId
+
+`TId` *extends* `string` = `string`
+
+### TDefault
+
+`TDefault` *extends*
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null` =
+ \| [`HotkeyChord`](../type-aliases/HotkeyChord.md)
+ \| [`HotkeySequence`](../type-aliases/HotkeySequence.md)
+ \| `null`
+
+## Properties
+
+### ~appHotkey
+
+```ts
+readonly ~appHotkey: true;
+```
+
+Defined in: [app-hotkeys.ts:75](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L75)
+
+Brand that distinguishes app hotkeys from raw hotkey objects.
+
+***
+
+### context?
+
+```ts
+readonly optional context?: string;
+```
+
+Defined in: [app-hotkeys.ts:83](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L83)
+
+***
+
+### defaultHotkey
+
+```ts
+readonly defaultHotkey: TDefault;
+```
+
+Defined in: [app-hotkeys.ts:81](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L81)
+
+Hotkey declared in `defineAppHotkeys`.
+
+***
+
+### hotkey
+
+```ts
+readonly hotkey: Hotkey | null;
+```
+
+Defined in: [app-hotkeys.ts:79](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L79)
+
+Effective hotkey: the user's custom hotkey, or the default. `null` means unbound.
+
+***
+
+### id
+
+```ts
+readonly id: TId;
+```
+
+Defined in: [app-hotkeys.ts:77](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L77)
+
+Stable id. Saved custom hotkeys are keyed by this value.
+
+***
+
+### meta?
+
+```ts
+readonly optional meta?: HotkeyMeta;
+```
+
+Defined in: [app-hotkeys.ts:82](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L82)
+
+***
+
+### options?
+
+```ts
+readonly optional options?: AppHotkeyOptions;
+```
+
+Defined in: [app-hotkeys.ts:84](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L84)
diff --git a/docs/reference/interfaces/AppHotkeyInput.md b/docs/reference/interfaces/AppHotkeyInput.md
new file mode 100644
index 00000000..4a3bde46
--- /dev/null
+++ b/docs/reference/interfaces/AppHotkeyInput.md
@@ -0,0 +1,59 @@
+---
+id: AppHotkeyInput
+title: AppHotkeyInput
+---
+
+Defined in: [app-hotkeys.ts:44](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L44)
+
+One declaration passed to `defineAppHotkeys`.
+
+## Properties
+
+### context?
+
+```ts
+optional context?: string;
+```
+
+Defined in: [app-hotkeys.ts:54](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L54)
+
+Label for where this hotkey applies, such as `'editor'`. App hotkeys with
+different contexts may share a hotkey; one without a context conflicts with
+any app hotkey that shares its hotkey. It does not affect matching.
+
+***
+
+### hotkey
+
+```ts
+hotkey: Hotkey | null;
+```
+
+Defined in: [app-hotkeys.ts:46](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L46)
+
+Default hotkey: a chord, a sequence, or `null` for an action without a default.
+
+***
+
+### meta?
+
+```ts
+optional meta?: HotkeyMeta;
+```
+
+Defined in: [app-hotkeys.ts:48](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L48)
+
+Display metadata for cheat sheets and settings screens.
+
+***
+
+### options?
+
+```ts
+optional options?: AppHotkeyOptions;
+```
+
+Defined in: [app-hotkeys.ts:59](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L59)
+
+Options that describe the hotkey itself. Chord defaults accept
+`requireReset`; sequence defaults accept `timeout`.
diff --git a/docs/reference/interfaces/AppHotkeyListItem.md b/docs/reference/interfaces/AppHotkeyListItem.md
new file mode 100644
index 00000000..309e25aa
--- /dev/null
+++ b/docs/reference/interfaces/AppHotkeyListItem.md
@@ -0,0 +1,58 @@
+---
+id: AppHotkeyListItem
+title: AppHotkeyListItem
+---
+
+Defined in: [app-hotkeys.ts:307](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L307)
+
+One row of an app hotkey cheat sheet.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`AppHotkey`](AppHotkey.md) = [`AppHotkey`](AppHotkey.md)
+
+## Properties
+
+### appHotkey
+
+```ts
+appHotkey: T;
+```
+
+Defined in: [app-hotkeys.ts:308](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L308)
+
+***
+
+### isCustom
+
+```ts
+isCustom: boolean;
+```
+
+Defined in: [app-hotkeys.ts:311](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L311)
+
+Whether the effective hotkey differs from the declared default.
+
+***
+
+### registrations
+
+```ts
+registrations: HotkeyRegistrationView[];
+```
+
+Defined in: [app-hotkeys.ts:313](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L313)
+
+Live registrations of this app hotkey (for example, one per list row).
+
+***
+
+### status
+
+```ts
+status: AppHotkeyStatus;
+```
+
+Defined in: [app-hotkeys.ts:309](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L309)
diff --git a/docs/reference/interfaces/AppHotkeysState.md b/docs/reference/interfaces/AppHotkeysState.md
new file mode 100644
index 00000000..10ae12f1
--- /dev/null
+++ b/docs/reference/interfaces/AppHotkeysState.md
@@ -0,0 +1,38 @@
+---
+id: AppHotkeysState
+title: AppHotkeysState
+---
+
+Defined in: [app-hotkeys.ts:317](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L317)
+
+State of an `AppHotkeysStore`.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`AppHotkeys`](../type-aliases/AppHotkeys.md) = [`AppHotkeys`](../type-aliases/AppHotkeys.md)
+
+## Properties
+
+### appHotkeys
+
+```ts
+appHotkeys: T;
+```
+
+Defined in: [app-hotkeys.ts:319](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L319)
+
+Effective app hotkeys: declarations with custom hotkeys applied.
+
+***
+
+### customHotkeys
+
+```ts
+customHotkeys: CustomHotkeys;
+```
+
+Defined in: [app-hotkeys.ts:321](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L321)
+
+The user's hotkeys that differ from the defaults.
diff --git a/docs/reference/interfaces/AppHotkeysStoreOptions.md b/docs/reference/interfaces/AppHotkeysStoreOptions.md
new file mode 100644
index 00000000..1fdcda8d
--- /dev/null
+++ b/docs/reference/interfaces/AppHotkeysStoreOptions.md
@@ -0,0 +1,60 @@
+---
+id: AppHotkeysStoreOptions
+title: AppHotkeysStoreOptions
+---
+
+Defined in: [app-hotkeys.ts:325](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L325)
+
+Options for `AppHotkeysStore`.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`AppHotkeys`](../type-aliases/AppHotkeys.md) = [`AppHotkeys`](../type-aliases/AppHotkeys.md)
+
+## Properties
+
+### customHotkeys?
+
+```ts
+optional customHotkeys?: CustomHotkeys | null;
+```
+
+Defined in: [app-hotkeys.ts:327](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L327)
+
+Starting custom hotkeys, such as saved data. Invalid entries are ignored with a warning.
+
+***
+
+### onCustomHotkeysChange?
+
+```ts
+optional onCustomHotkeysChange?: (customHotkeys) => void;
+```
+
+Defined in: [app-hotkeys.ts:329](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L329)
+
+Called with the custom hotkeys after every change, ready to save.
+
+#### Parameters
+
+##### customHotkeys
+
+[`CustomHotkeys`](../type-aliases/CustomHotkeys.md)\<`T`\>
+
+#### Returns
+
+`void`
+
+***
+
+### platform?
+
+```ts
+optional platform?: Platform;
+```
+
+Defined in: [app-hotkeys.ts:331](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L331)
+
+Platform used to compare hotkeys. Defaults to detection.
diff --git a/docs/reference/interfaces/CreateHotkeyHandlerOptions.md b/docs/reference/interfaces/CreateHotkeyHandlerOptions.md
index 5ea774b2..d822a7cd 100644
--- a/docs/reference/interfaces/CreateHotkeyHandlerOptions.md
+++ b/docs/reference/interfaces/CreateHotkeyHandlerOptions.md
@@ -3,7 +3,7 @@ id: CreateHotkeyHandlerOptions
title: CreateHotkeyHandlerOptions
---
-Defined in: [match.ts:60](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L60)
+Defined in: [match.ts:68](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L68)
Options for creating a hotkey handler.
@@ -15,7 +15,7 @@ Options for creating a hotkey handler.
optional platform?: "mac" | "windows" | "linux";
```
-Defined in: [match.ts:66](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L66)
+Defined in: [match.ts:74](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L74)
The target platform for resolving 'Mod'
@@ -27,7 +27,7 @@ The target platform for resolving 'Mod'
optional preventDefault?: boolean;
```
-Defined in: [match.ts:62](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L62)
+Defined in: [match.ts:70](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L70)
Prevent the default browser action when the hotkey matches. Defaults to true
@@ -39,6 +39,6 @@ Prevent the default browser action when the hotkey matches. Defaults to true
optional stopPropagation?: boolean;
```
-Defined in: [match.ts:64](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L64)
+Defined in: [match.ts:72](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L72)
Stop event propagation when the hotkey matches. Defaults to true
diff --git a/docs/reference/interfaces/FormatDisplayOptions.md b/docs/reference/interfaces/FormatDisplayOptions.md
index 5376a47d..82081016 100644
--- a/docs/reference/interfaces/FormatDisplayOptions.md
+++ b/docs/reference/interfaces/FormatDisplayOptions.md
@@ -3,7 +3,7 @@ id: FormatDisplayOptions
title: FormatDisplayOptions
---
-Defined in: [format.ts:195](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L195)
+Defined in: [format.ts:210](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L210)
Options for formatting hotkeys for display.
@@ -15,7 +15,7 @@ Options for formatting hotkeys for display.
optional keyLabels?: Readonly>;
```
-Defined in: [format.ts:210](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L210)
+Defined in: [format.ts:225](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L225)
Final display overrides for logical keys or physical codes; take precedence over layoutMap. Never changes matching.
@@ -27,7 +27,7 @@ Final display overrides for logical keys or physical codes; take precedence over
optional layoutMap?: object;
```
-Defined in: [format.ts:208](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L208)
+Defined in: [format.ts:223](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L223)
An already-resolved code-to-key map, such as KeyboardLayoutMap or Map.
Used only for physical bindings. Mapped keys receive normal display formatting;
@@ -58,7 +58,7 @@ get: (code) => string | undefined;
optional parts?: boolean;
```
-Defined in: [format.ts:201](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L201)
+Defined in: [format.ts:216](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L216)
Return individual key labels instead of a joined string. Default: false.
@@ -70,7 +70,7 @@ Return individual key labels instead of a joined string. Default: false.
optional platform?: "mac" | "windows" | "linux";
```
-Defined in: [format.ts:197](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L197)
+Defined in: [format.ts:212](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L212)
The target platform. Defaults to auto-detection.
@@ -82,12 +82,24 @@ The target platform. Defaults to auto-detection.
optional separatorToken?: string | null;
```
-Defined in: [format.ts:212](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L212)
+Defined in: [format.ts:227](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L227)
Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined.
***
+### sequenceSeparator?
+
+```ts
+optional sequenceSeparator?: string;
+```
+
+Defined in: [format.ts:229](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L229)
+
+Separator between sequence steps. Default: a space.
+
+***
+
### useSymbols?
```ts
@@ -99,6 +111,6 @@ optional useSymbols?:
};
```
-Defined in: [format.ts:199](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L199)
+Defined in: [format.ts:214](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L214)
Whether to use symbols for the display. Defaults to true.
diff --git a/docs/reference/interfaces/HotkeyCallbackContext.md b/docs/reference/interfaces/HotkeyCallbackContext.md
index 09db246e..0236a5c6 100644
--- a/docs/reference/interfaces/HotkeyCallbackContext.md
+++ b/docs/reference/interfaces/HotkeyCallbackContext.md
@@ -3,7 +3,7 @@ id: HotkeyCallbackContext
title: HotkeyCallbackContext
---
-Defined in: [hotkey.types.ts:212](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L212)
+Defined in: [hotkey.types.ts:229](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L229)
Context passed to hotkey callbacks along with the keyboard event.
@@ -15,9 +15,9 @@ Context passed to hotkey callbacks along with the keyboard event.
hotkey: Hotkey;
```
-Defined in: [hotkey.types.ts:214](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L214)
+Defined in: [hotkey.types.ts:231](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L231)
-The original hotkey string that was registered
+The registered hotkey: a chord string or a sequence
***
@@ -27,6 +27,6 @@ The original hotkey string that was registered
parsedHotkey: ParsedHotkey;
```
-Defined in: [hotkey.types.ts:216](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L216)
+Defined in: [hotkey.types.ts:233](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L233)
-The parsed representation of the hotkey
+The parsed chord that completed the match (the last step of a sequence)
diff --git a/docs/reference/interfaces/HotkeyChordOptions.md b/docs/reference/interfaces/HotkeyChordOptions.md
new file mode 100644
index 00000000..07720320
--- /dev/null
+++ b/docs/reference/interfaces/HotkeyChordOptions.md
@@ -0,0 +1,186 @@
+---
+id: HotkeyChordOptions
+title: HotkeyChordOptions
+---
+
+Defined in: [hotkey-manager.ts:73](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L73)
+
+Options for a single chord such as `'Mod+S'`.
+
+## Extends
+
+- [`HotkeyOptions`](HotkeyOptions.md)
+
+## Properties
+
+### appHotkeyId?
+
+```ts
+optional appHotkeyId?: string;
+```
+
+Defined in: [hotkey-manager.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L69)
+
+Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`.
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`appHotkeyId`](HotkeyOptions.md#apphotkeyid)
+
+***
+
+### conflictBehavior?
+
+```ts
+optional conflictBehavior?: ConflictBehavior;
+```
+
+Defined in: [hotkey-manager.ts:47](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L47)
+
+Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn'
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`conflictBehavior`](HotkeyOptions.md#conflictbehavior)
+
+***
+
+### enabled?
+
+```ts
+optional enabled?: boolean;
+```
+
+Defined in: [hotkey-manager.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L53)
+
+Soft-disable: when `false`, the callback does not run but the registration
+stays in `HotkeyManager` (and in devtools). Toggling this should update the
+existing handle via `setOptions` rather than unregistering. Defaults to `true`.
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`enabled`](HotkeyOptions.md#enabled)
+
+***
+
+### eventType?
+
+```ts
+optional eventType?: "keyup" | "keydown";
+```
+
+Defined in: [hotkey-manager.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L55)
+
+The event type to listen for. Defaults to 'keydown'
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`eventType`](HotkeyOptions.md#eventtype)
+
+***
+
+### ignoreInputs?
+
+```ts
+optional ignoreInputs?: boolean;
+```
+
+Defined in: [hotkey-manager.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L57)
+
+Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on the hotkey (the first step of a sequence): true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`ignoreInputs`](HotkeyOptions.md#ignoreinputs)
+
+***
+
+### meta?
+
+```ts
+optional meta?: HotkeyMeta;
+```
+
+Defined in: [hotkey-manager.ts:67](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L67)
+
+Optional metadata (name, description, custom fields via declaration merging)
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`meta`](HotkeyOptions.md#meta)
+
+***
+
+### platform?
+
+```ts
+optional platform?: "mac" | "windows" | "linux";
+```
+
+Defined in: [hotkey-manager.ts:59](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L59)
+
+The target platform for resolving 'Mod'
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`platform`](HotkeyOptions.md#platform)
+
+***
+
+### preventDefault?
+
+```ts
+optional preventDefault?: boolean;
+```
+
+Defined in: [hotkey-manager.ts:61](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L61)
+
+Prevent the default browser action when the hotkey matches. Defaults to true
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`preventDefault`](HotkeyOptions.md#preventdefault)
+
+***
+
+### requireReset?
+
+```ts
+optional requireReset?: boolean;
+```
+
+Defined in: [hotkey-manager.ts:75](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L75)
+
+If true, only trigger once until all keys are released. Default: false
+
+***
+
+### stopPropagation?
+
+```ts
+optional stopPropagation?: boolean;
+```
+
+Defined in: [hotkey-manager.ts:63](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L63)
+
+Stop event propagation when the hotkey matches. Defaults to true
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`stopPropagation`](HotkeyOptions.md#stoppropagation)
+
+***
+
+### target?
+
+```ts
+optional target?: Target | null;
+```
+
+Defined in: [hotkey-manager.ts:65](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L65)
+
+The DOM element to attach the event listener to. Defaults to document.
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`target`](HotkeyOptions.md#target)
diff --git a/docs/reference/interfaces/HotkeyRecorderOptions.md b/docs/reference/interfaces/HotkeyChordRecorderOptions.md
similarity index 54%
rename from docs/reference/interfaces/HotkeyRecorderOptions.md
rename to docs/reference/interfaces/HotkeyChordRecorderOptions.md
index 98c9c661..02f6c9fe 100644
--- a/docs/reference/interfaces/HotkeyRecorderOptions.md
+++ b/docs/reference/interfaces/HotkeyChordRecorderOptions.md
@@ -1,15 +1,15 @@
---
-id: HotkeyRecorderOptions
-title: HotkeyRecorderOptions
+id: HotkeyChordRecorderOptions
+title: HotkeyChordRecorderOptions
---
-Defined in: [hotkey-recorder.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L33)
+Defined in: [hotkey-recorder.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L53)
-Options for configuring a HotkeyRecorder instance.
+Options for recording a single chord. This is the default (`maxSteps: 1`).
## Extends
-- [`RecorderOptions`](RecorderOptions.md)
+- `HotkeyRecorderBaseOptions`
## Properties
@@ -25,7 +25,9 @@ Opt in to live-registry conflicts, including sequence prefixes. Default: false.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`detectConflicts`](RecorderOptions.md#detectconflicts)
+```ts
+HotkeyRecorderBaseOptions.detectConflicts
+```
***
@@ -35,19 +37,30 @@ Opt in to live-registry conflicts, including sequence prefixes. Default: false.
optional ignoreInputs?: boolean;
```
-Defined in: [hotkey-recorder.ts:52](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L52)
+Defined in: [hotkey-recorder.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L49)
Whether to ignore keyboard events from input-like elements (text inputs,
-textarea, select, contenteditable). When true, typing in inputs passes
-through normally instead of being captured as a hotkey recording.
-Escape always works regardless of this setting.
+textarea, select, contenteditable) while recording. When true, typing in
+inputs passes through normally (Escape still cancels). Defaults to true.
+
+#### Inherited from
+
+```ts
+HotkeyRecorderBaseOptions.ignoreInputs
+```
-#### Default
+***
+
+### maxSteps?
```ts
-true
+optional maxSteps?: 1;
```
+Defined in: [hotkey-recorder.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L55)
+
+Maximum number of chords to record. Default: 1
+
***
### onCancel?
@@ -56,7 +69,7 @@ true
optional onCancel?: () => void;
```
-Defined in: [hotkey-recorder.ts:42](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L42)
+Defined in: [hotkey-recorder.ts:38](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L38)
Optional callback when recording is cancelled (Escape pressed)
@@ -64,6 +77,12 @@ Optional callback when recording is cancelled (Escape pressed)
`void`
+#### Inherited from
+
+```ts
+HotkeyRecorderBaseOptions.onCancel
+```
+
***
### onClear?
@@ -72,14 +91,21 @@ Optional callback when recording is cancelled (Escape pressed)
optional onClear?: () => void;
```
-Defined in: [hotkey-recorder.ts:44](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L44)
+Defined in: [hotkey-recorder.ts:43](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L43)
-Optional callback when shortcut is cleared (Backspace/Delete pressed)
+Optional callback when the recording is cleared: Backspace/Delete with no
+modifiers and no recorded steps
#### Returns
`void`
+#### Inherited from
+
+```ts
+HotkeyRecorderBaseOptions.onClear
+```
+
***
### onRecord
@@ -88,15 +114,15 @@ Optional callback when shortcut is cleared (Backspace/Delete pressed)
onRecord: (hotkey) => void;
```
-Defined in: [hotkey-recorder.ts:40](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L40)
+Defined in: [hotkey-recorder.ts:62](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L62)
-Callback when a hotkey is successfully recorded
+Callback when a chord is successfully recorded
#### Parameters
##### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md)
+[`HotkeyChord`](../type-aliases/HotkeyChord.md)
#### Returns
@@ -126,7 +152,9 @@ Rejected candidates leave recording active.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`onReject`](RecorderOptions.md#onreject)
+```ts
+HotkeyRecorderBaseOptions.onReject
+```
***
@@ -142,7 +170,9 @@ Platform used for Mod and AltGraph handling. Defaults to platform detection.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`platform`](RecorderOptions.md#platform)
+```ts
+HotkeyRecorderBaseOptions.platform
+```
***
@@ -158,7 +188,9 @@ Physical code recording is the default. Choose key to record logical characters.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`recordBy`](RecorderOptions.md#recordby)
+```ts
+HotkeyRecorderBaseOptions.recordBy
+```
***
@@ -168,7 +200,7 @@ Physical code recording is the default. Choose key to record logical characters.
optional validate?: (hotkey, context) => string | boolean;
```
-Defined in: [hotkey-recorder.ts:35](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L35)
+Defined in: [hotkey-recorder.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L57)
Return true to accept, or false/a message to reject while staying in recording mode.
@@ -176,7 +208,7 @@ Return true to accept, or false/a message to reject while staying in recording m
##### hotkey
-[`Hotkey`](../type-aliases/Hotkey.md)
+[`HotkeyChord`](../type-aliases/HotkeyChord.md)
##### context
diff --git a/docs/reference/interfaces/HotkeyChordRegistration.md b/docs/reference/interfaces/HotkeyChordRegistration.md
new file mode 100644
index 00000000..7788066c
--- /dev/null
+++ b/docs/reference/interfaces/HotkeyChordRegistration.md
@@ -0,0 +1,174 @@
+---
+id: HotkeyChordRegistration
+title: HotkeyChordRegistration
+---
+
+Defined in: [hotkey-manager.ts:112](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L112)
+
+A registered chord in the HotkeyManager.
+
+## Extends
+
+- `RegistrationBase`\<[`HotkeyChordOptions`](HotkeyChordOptions.md)\>
+
+## Properties
+
+### activeMatch?
+
+```ts
+optional activeMatch?: object;
+```
+
+Defined in: [hotkey-manager.ts:117](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L117)
+
+The concrete key/code that activated a requireReset registration.
+
+#### code
+
+```ts
+code: string;
+```
+
+#### key
+
+```ts
+key: string;
+```
+
+***
+
+### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+Defined in: [hotkey-manager.ts:100](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L100)
+
+The callback to invoke
+
+#### Inherited from
+
+```ts
+RegistrationBase.callback
+```
+
+***
+
+### hasFired
+
+```ts
+hasFired: boolean;
+```
+
+Defined in: [hotkey-manager.ts:108](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L108)
+
+Whether this registration has fired (and, for requireReset chords, needs a reset)
+
+#### Inherited from
+
+```ts
+RegistrationBase.hasFired
+```
+
+***
+
+### hotkey
+
+```ts
+hotkey: HotkeyChord;
+```
+
+Defined in: [hotkey-manager.ts:114](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L114)
+
+***
+
+### id
+
+```ts
+id: string;
+```
+
+Defined in: [hotkey-manager.ts:98](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L98)
+
+Unique identifier for this registration
+
+#### Inherited from
+
+```ts
+RegistrationBase.id
+```
+
+***
+
+### kind
+
+```ts
+kind: "chord";
+```
+
+Defined in: [hotkey-manager.ts:113](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L113)
+
+***
+
+### options
+
+```ts
+options: HotkeyChordOptions;
+```
+
+Defined in: [hotkey-manager.ts:102](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L102)
+
+Resolved options for this registration
+
+#### Inherited from
+
+```ts
+RegistrationBase.options
+```
+
+***
+
+### parsedHotkey
+
+```ts
+parsedHotkey: ParsedHotkey;
+```
+
+Defined in: [hotkey-manager.ts:115](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L115)
+
+***
+
+### target
+
+```ts
+target: Target;
+```
+
+Defined in: [hotkey-manager.ts:104](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L104)
+
+The resolved target element for this registration
+
+#### Inherited from
+
+```ts
+RegistrationBase.target
+```
+
+***
+
+### triggerCount
+
+```ts
+triggerCount: number;
+```
+
+Defined in: [hotkey-manager.ts:106](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L106)
+
+How many times this registration's callback has been triggered
+
+#### Inherited from
+
+```ts
+RegistrationBase.triggerCount
+```
diff --git a/docs/reference/interfaces/HotkeyChordRegistrationView.md b/docs/reference/interfaces/HotkeyChordRegistrationView.md
new file mode 100644
index 00000000..3d428710
--- /dev/null
+++ b/docs/reference/interfaces/HotkeyChordRegistrationView.md
@@ -0,0 +1,116 @@
+---
+id: HotkeyChordRegistrationView
+title: HotkeyChordRegistrationView
+---
+
+Defined in: [hotkey-manager.ts:143](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L143)
+
+Public view of a chord registration, without its callback.
+
+## Extends
+
+- `RegistrationViewBase`
+
+## Properties
+
+### hasFired
+
+```ts
+hasFired: boolean;
+```
+
+Defined in: [hotkey-manager.ts:139](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L139)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.hasFired
+```
+
+***
+
+### hotkey
+
+```ts
+hotkey: HotkeyChord;
+```
+
+Defined in: [hotkey-manager.ts:145](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L145)
+
+***
+
+### id
+
+```ts
+id: string;
+```
+
+Defined in: [hotkey-manager.ts:136](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L136)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.id
+```
+
+***
+
+### kind
+
+```ts
+kind: "chord";
+```
+
+Defined in: [hotkey-manager.ts:144](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L144)
+
+***
+
+### options
+
+```ts
+options: HotkeyChordOptions;
+```
+
+Defined in: [hotkey-manager.ts:147](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L147)
+
+***
+
+### parsedHotkey
+
+```ts
+parsedHotkey: ParsedHotkey;
+```
+
+Defined in: [hotkey-manager.ts:146](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L146)
+
+***
+
+### target
+
+```ts
+target: Target;
+```
+
+Defined in: [hotkey-manager.ts:137](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L137)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.target
+```
+
+***
+
+### triggerCount
+
+```ts
+triggerCount: number;
+```
+
+Defined in: [hotkey-manager.ts:138](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L138)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.triggerCount
+```
diff --git a/docs/reference/interfaces/HotkeyConflict.md b/docs/reference/interfaces/HotkeyConflict.md
new file mode 100644
index 00000000..7d7b5eed
--- /dev/null
+++ b/docs/reference/interfaces/HotkeyConflict.md
@@ -0,0 +1,18 @@
+---
+id: HotkeyConflict
+title: HotkeyConflict
+---
+
+Defined in: [conflicts.ts:13](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L13)
+
+A live registration that overlaps a candidate hotkey.
+
+## Properties
+
+### registration
+
+```ts
+registration: HotkeyRegistrationView;
+```
+
+Defined in: [conflicts.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L14)
diff --git a/docs/reference/interfaces/HotkeyConflictOptions.md b/docs/reference/interfaces/HotkeyConflictOptions.md
index 5a695e13..c085cc41 100644
--- a/docs/reference/interfaces/HotkeyConflictOptions.md
+++ b/docs/reference/interfaces/HotkeyConflictOptions.md
@@ -3,7 +3,7 @@ id: HotkeyConflictOptions
title: HotkeyConflictOptions
---
-Defined in: [conflicts.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L15)
+Defined in: [conflicts.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L17)
## Properties
@@ -25,7 +25,7 @@ Source events allow detecting physical/logical overlap on the recorded layout.
optional eventType?: "keyup" | "keydown";
```
-Defined in: [conflicts.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L21)
+Defined in: [conflicts.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L23)
Intended event type. Default: keydown.
@@ -37,7 +37,7 @@ Intended event type. Default: keydown.
optional exclude?: (registration) => boolean;
```
-Defined in: [conflicts.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L27)
+Defined in: [conflicts.ts:29](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L29)
Additional app-specific exclusions, such as all instances of one action.
@@ -45,8 +45,7 @@ Additional app-specific exclusions, such as all instances of one action.
##### registration
- \| [`HotkeyRegistrationView`](HotkeyRegistrationView.md)
- \| [`SequenceRegistrationView`](SequenceRegistrationView.md)
+[`HotkeyRegistrationView`](../type-aliases/HotkeyRegistrationView.md)
#### Returns
@@ -60,7 +59,7 @@ Additional app-specific exclusions, such as all instances of one action.
optional excludeIds?: readonly string[];
```
-Defined in: [conflicts.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L25)
+Defined in: [conflicts.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L27)
IDs of registrations being edited.
@@ -72,7 +71,7 @@ IDs of registrations being edited.
optional includeDisabled?: boolean;
```
-Defined in: [conflicts.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L23)
+Defined in: [conflicts.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L25)
Include disabled registrations. Default: false.
@@ -96,7 +95,7 @@ Platform used to resolve Mod in the candidate. Registrations retain their own pl
optional scope?: "all" | "overlapping";
```
-Defined in: [conflicts.ts:19](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L19)
+Defined in: [conflicts.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L21)
Check all targets instead of overlapping targets. Default: overlapping.
@@ -108,6 +107,6 @@ Check all targets instead of overlapping targets. Default: overlapping.
optional target?: Document | Window | HTMLElement;
```
-Defined in: [conflicts.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L17)
+Defined in: [conflicts.ts:19](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L19)
Intended registration target. Defaults to document; disjoint targets are excluded.
diff --git a/docs/reference/interfaces/HotkeyMeta.md b/docs/reference/interfaces/HotkeyMeta.md
index 4425f11c..4cf85c3b 100644
--- a/docs/reference/interfaces/HotkeyMeta.md
+++ b/docs/reference/interfaces/HotkeyMeta.md
@@ -3,9 +3,9 @@ id: HotkeyMeta
title: HotkeyMeta
---
-Defined in: [hotkey.types.ts:252](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L252)
+Defined in: [hotkey.types.ts:269](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L269)
-Metadata for hotkey and sequence registrations.
+Metadata for hotkey registrations, chords and sequences alike.
Includes `name`, `description`, and `group` by default. Extend via declaration merging:
## Example
@@ -27,7 +27,7 @@ declare module '@tanstack/hotkeys' {
optional description?: string;
```
-Defined in: [hotkey.types.ts:256](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L256)
+Defined in: [hotkey.types.ts:273](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L273)
Description of what this hotkey does
@@ -39,7 +39,7 @@ Description of what this hotkey does
optional group?: string;
```
-Defined in: [hotkey.types.ts:258](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L258)
+Defined in: [hotkey.types.ts:275](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L275)
Optional display group. Does not affect matching or scope.
@@ -51,6 +51,6 @@ Optional display group. Does not affect matching or scope.
optional name?: string;
```
-Defined in: [hotkey.types.ts:254](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L254)
+Defined in: [hotkey.types.ts:271](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L271)
Human-readable name for this hotkey (e.g., "Save Document")
diff --git a/docs/reference/interfaces/HotkeyOptions.md b/docs/reference/interfaces/HotkeyOptions.md
index 5bbc1596..1de688b0 100644
--- a/docs/reference/interfaces/HotkeyOptions.md
+++ b/docs/reference/interfaces/HotkeyOptions.md
@@ -3,19 +3,36 @@ id: HotkeyOptions
title: HotkeyOptions
---
-Defined in: [hotkey-manager.ts:31](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L31)
+Defined in: [hotkey-manager.ts:45](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L45)
+
+Options shared by chords and sequences.
-Options for registering a hotkey.
+## Extended by
+
+- [`HotkeyChordOptions`](HotkeyChordOptions.md)
+- [`HotkeySequenceOptions`](HotkeySequenceOptions.md)
## Properties
+### appHotkeyId?
+
+```ts
+optional appHotkeyId?: string;
+```
+
+Defined in: [hotkey-manager.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L69)
+
+Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`.
+
+***
+
### conflictBehavior?
```ts
optional conflictBehavior?: ConflictBehavior;
```
-Defined in: [hotkey-manager.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L33)
+Defined in: [hotkey-manager.ts:47](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L47)
Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn'
@@ -27,7 +44,7 @@ Behavior when this hotkey conflicts with an existing registration on the same ta
optional enabled?: boolean;
```
-Defined in: [hotkey-manager.ts:39](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L39)
+Defined in: [hotkey-manager.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L53)
Soft-disable: when `false`, the callback does not run but the registration
stays in `HotkeyManager` (and in devtools). Toggling this should update the
@@ -41,7 +58,7 @@ existing handle via `setOptions` rather than unregistering. Defaults to `true`.
optional eventType?: "keyup" | "keydown";
```
-Defined in: [hotkey-manager.ts:41](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L41)
+Defined in: [hotkey-manager.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L55)
The event type to listen for. Defaults to 'keydown'
@@ -53,9 +70,9 @@ The event type to listen for. Defaults to 'keydown'
optional ignoreInputs?: boolean;
```
-Defined in: [hotkey-manager.ts:43](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L43)
+Defined in: [hotkey-manager.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L57)
-Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape
+Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on the hotkey (the first step of a sequence): true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape
***
@@ -65,7 +82,7 @@ Whether to ignore hotkeys when keyboard events originate from input-like element
optional meta?: HotkeyMeta;
```
-Defined in: [hotkey-manager.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L55)
+Defined in: [hotkey-manager.ts:67](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L67)
Optional metadata (name, description, custom fields via declaration merging)
@@ -77,7 +94,7 @@ Optional metadata (name, description, custom fields via declaration merging)
optional platform?: "mac" | "windows" | "linux";
```
-Defined in: [hotkey-manager.ts:45](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L45)
+Defined in: [hotkey-manager.ts:59](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L59)
The target platform for resolving 'Mod'
@@ -89,31 +106,19 @@ The target platform for resolving 'Mod'
optional preventDefault?: boolean;
```
-Defined in: [hotkey-manager.ts:47](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L47)
+Defined in: [hotkey-manager.ts:61](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L61)
Prevent the default browser action when the hotkey matches. Defaults to true
***
-### requireReset?
-
-```ts
-optional requireReset?: boolean;
-```
-
-Defined in: [hotkey-manager.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L49)
-
-If true, only trigger once until all keys are released. Default: false
-
-***
-
### stopPropagation?
```ts
optional stopPropagation?: boolean;
```
-Defined in: [hotkey-manager.ts:51](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L51)
+Defined in: [hotkey-manager.ts:63](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L63)
Stop event propagation when the hotkey matches. Defaults to true
@@ -122,9 +127,9 @@ Stop event propagation when the hotkey matches. Defaults to true
### target?
```ts
-optional target?: Document | Window | HTMLElement | null;
+optional target?: Target | null;
```
-Defined in: [hotkey-manager.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L53)
+Defined in: [hotkey-manager.ts:65](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L65)
The DOM element to attach the event listener to. Defaults to document.
diff --git a/docs/reference/interfaces/HotkeyRecorderState.md b/docs/reference/interfaces/HotkeyRecorderState.md
index 0d1b0769..94e9145e 100644
--- a/docs/reference/interfaces/HotkeyRecorderState.md
+++ b/docs/reference/interfaces/HotkeyRecorderState.md
@@ -3,7 +3,7 @@ id: HotkeyRecorderState
title: HotkeyRecorderState
---
-Defined in: [hotkey-recorder.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L23)
+Defined in: [hotkey-recorder.ts:24](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L24)
State interface for the HotkeyRecorder.
@@ -15,7 +15,7 @@ State interface for the HotkeyRecorder.
isRecording: boolean;
```
-Defined in: [hotkey-recorder.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L25)
+Defined in: [hotkey-recorder.ts:26](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L26)
Whether recording is currently active
@@ -27,6 +27,18 @@ Whether recording is currently active
recordedHotkey: Hotkey | null;
```
-Defined in: [hotkey-recorder.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L27)
+Defined in: [hotkey-recorder.ts:30](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L30)
-The currently recorded hotkey (for live preview)
+The last committed hotkey: a chord, or a sequence of two or more steps
+
+***
+
+### steps
+
+```ts
+steps: HotkeySequence;
+```
+
+Defined in: [hotkey-recorder.ts:28](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L28)
+
+Chords recorded so far in a multi-step recording (empty for `maxSteps: 1`)
diff --git a/docs/reference/interfaces/HotkeyRecorderValidationContext.md b/docs/reference/interfaces/HotkeyRecorderValidationContext.md
index 03431de1..0510fa6a 100644
--- a/docs/reference/interfaces/HotkeyRecorderValidationContext.md
+++ b/docs/reference/interfaces/HotkeyRecorderValidationContext.md
@@ -3,7 +3,9 @@ id: HotkeyRecorderValidationContext
title: HotkeyRecorderValidationContext
---
-Defined in: [recorder-options.ts:26](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L26)
+Defined in: [recorder-options.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L27)
+
+Validation context for a recorded chord or sequence.
## Properties
@@ -13,7 +15,21 @@ Defined in: [recorder-options.ts:26](https://github.com/TanStack/hotkeys/blob/ma
event: KeyboardEvent;
```
-Defined in: [recorder-options.ts:27](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L27)
+Defined in: [recorder-options.ts:29](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L29)
+
+The event that recorded the last chord.
+
+***
+
+### events
+
+```ts
+events: readonly KeyboardEvent[];
+```
+
+Defined in: [recorder-options.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L33)
+
+The event that recorded each step.
***
@@ -23,4 +39,18 @@ Defined in: [recorder-options.ts:27](https://github.com/TanStack/hotkeys/blob/ma
parsedHotkey: ParsedHotkey;
```
-Defined in: [recorder-options.ts:28](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L28)
+Defined in: [recorder-options.ts:31](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L31)
+
+The last chord, parsed.
+
+***
+
+### parsedSequence
+
+```ts
+parsedSequence: readonly ParsedHotkey[];
+```
+
+Defined in: [recorder-options.ts:35](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L35)
+
+Every step, parsed.
diff --git a/docs/reference/interfaces/HotkeyRegistration.md b/docs/reference/interfaces/HotkeyRegistration.md
deleted file mode 100644
index 944b2f40..00000000
--- a/docs/reference/interfaces/HotkeyRegistration.md
+++ /dev/null
@@ -1,128 +0,0 @@
----
-id: HotkeyRegistration
-title: HotkeyRegistration
----
-
-Defined in: [hotkey-manager.ts:61](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L61)
-
-A registered hotkey handler in the HotkeyManager.
-
-## Properties
-
-### activeMatch?
-
-```ts
-optional activeMatch?: object;
-```
-
-Defined in: [hotkey-manager.ts:67](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L67)
-
-The concrete key/code that activated a requireReset registration.
-
-#### code
-
-```ts
-code: string;
-```
-
-#### key
-
-```ts
-key: string;
-```
-
-***
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [hotkey-manager.ts:63](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L63)
-
-The callback to invoke
-
-***
-
-### hasFired
-
-```ts
-hasFired: boolean;
-```
-
-Defined in: [hotkey-manager.ts:65](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L65)
-
-Whether this registration has fired and needs reset (for requireReset)
-
-***
-
-### hotkey
-
-```ts
-hotkey: Hotkey;
-```
-
-Defined in: [hotkey-manager.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L69)
-
-The original hotkey string
-
-***
-
-### id
-
-```ts
-id: string;
-```
-
-Defined in: [hotkey-manager.ts:71](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L71)
-
-Unique identifier for this registration
-
-***
-
-### options
-
-```ts
-options: HotkeyOptions;
-```
-
-Defined in: [hotkey-manager.ts:73](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L73)
-
-Options for this registration
-
-***
-
-### parsedHotkey
-
-```ts
-parsedHotkey: ParsedHotkey;
-```
-
-Defined in: [hotkey-manager.ts:75](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L75)
-
-The parsed hotkey
-
-***
-
-### target
-
-```ts
-target: Document | Window | HTMLElement;
-```
-
-Defined in: [hotkey-manager.ts:77](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L77)
-
-The resolved target element for this registration
-
-***
-
-### triggerCount
-
-```ts
-triggerCount: number;
-```
-
-Defined in: [hotkey-manager.ts:79](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L79)
-
-How many times this registration's callback has been triggered
diff --git a/docs/reference/interfaces/HotkeyRegistrationHandle.md b/docs/reference/interfaces/HotkeyRegistrationHandle.md
index 33d2dfaf..e9de1fe0 100644
--- a/docs/reference/interfaces/HotkeyRegistrationHandle.md
+++ b/docs/reference/interfaces/HotkeyRegistrationHandle.md
@@ -3,7 +3,7 @@ id: HotkeyRegistrationHandle
title: HotkeyRegistrationHandle
---
-Defined in: [hotkey-manager.ts:144](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L144)
+Defined in: [hotkey-manager.ts:219](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L219)
A handle returned from HotkeyManager.register() that allows updating
the callback and options without re-registering the hotkey.
@@ -19,15 +19,18 @@ handle.callback = newCallback
// Update options without re-registering
handle.setOptions({ enabled: false })
-// Check if still active
-if (handle.isActive) {
- // ...
-}
-
// Unregister when done
handle.unregister()
```
+## Type Parameters
+
+### TOptions
+
+`TOptions` *extends* [`HotkeyOptions`](HotkeyOptions.md) =
+ \| [`HotkeyChordOptions`](HotkeyChordOptions.md)
+ \| [`HotkeySequenceOptions`](HotkeySequenceOptions.md)
+
## Properties
### callback
@@ -36,7 +39,7 @@ handle.unregister()
callback: HotkeyCallback;
```
-Defined in: [hotkey-manager.ts:149](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L149)
+Defined in: [hotkey-manager.ts:226](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L226)
The callback function. Can be set directly to update without re-registering.
This avoids stale closures when the callback references React state.
@@ -49,7 +52,7 @@ This avoids stale closures when the callback references React state.
readonly id: string;
```
-Defined in: [hotkey-manager.ts:151](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L151)
+Defined in: [hotkey-manager.ts:228](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L228)
Unique identifier for this registration
@@ -61,7 +64,7 @@ Unique identifier for this registration
readonly isActive: boolean;
```
-Defined in: [hotkey-manager.ts:153](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L153)
+Defined in: [hotkey-manager.ts:230](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L230)
Check if this registration is still active (not unregistered)
@@ -73,7 +76,7 @@ Check if this registration is still active (not unregistered)
setOptions: (options) => void;
```
-Defined in: [hotkey-manager.ts:158](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L158)
+Defined in: [hotkey-manager.ts:235](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L235)
Update options (merged with existing options).
Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
@@ -82,7 +85,7 @@ Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
##### options
-`Partial`\<[`HotkeyOptions`](HotkeyOptions.md)\>
+`Partial`\<`TOptions`\>
#### Returns
@@ -96,7 +99,7 @@ Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
unregister: () => void;
```
-Defined in: [hotkey-manager.ts:160](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L160)
+Defined in: [hotkey-manager.ts:237](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L237)
Unregister this hotkey
diff --git a/docs/reference/interfaces/HotkeyRegistrationView.md b/docs/reference/interfaces/HotkeyRegistrationView.md
deleted file mode 100644
index 71c34bb8..00000000
--- a/docs/reference/interfaces/HotkeyRegistrationView.md
+++ /dev/null
@@ -1,93 +0,0 @@
----
-id: HotkeyRegistrationView
-title: HotkeyRegistrationView
----
-
-Defined in: [hotkey-manager.ts:86](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L86)
-
-Public view of a hotkey registration for display and introspection.
-Omits the callback function which is an internal implementation detail.
-
-## Properties
-
-### hasFired
-
-```ts
-hasFired: boolean;
-```
-
-Defined in: [hotkey-manager.ts:100](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L100)
-
-Whether this registration has fired and needs reset (for requireReset)
-
-***
-
-### hotkey
-
-```ts
-hotkey: Hotkey;
-```
-
-Defined in: [hotkey-manager.ts:88](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L88)
-
-The original hotkey string
-
-***
-
-### id
-
-```ts
-id: string;
-```
-
-Defined in: [hotkey-manager.ts:90](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L90)
-
-Unique identifier for this registration
-
-***
-
-### options
-
-```ts
-options: HotkeyOptions;
-```
-
-Defined in: [hotkey-manager.ts:92](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L92)
-
-Options for this registration
-
-***
-
-### parsedHotkey
-
-```ts
-parsedHotkey: ParsedHotkey;
-```
-
-Defined in: [hotkey-manager.ts:94](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L94)
-
-The parsed hotkey
-
-***
-
-### target
-
-```ts
-target: Document | Window | HTMLElement;
-```
-
-Defined in: [hotkey-manager.ts:96](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L96)
-
-The resolved target element for this registration
-
-***
-
-### triggerCount
-
-```ts
-triggerCount: number;
-```
-
-Defined in: [hotkey-manager.ts:98](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L98)
-
-How many times this registration's callback has been triggered
diff --git a/docs/reference/interfaces/SequenceOptions.md b/docs/reference/interfaces/HotkeySequenceOptions.md
similarity index 61%
rename from docs/reference/interfaces/SequenceOptions.md
rename to docs/reference/interfaces/HotkeySequenceOptions.md
index 19991eb2..46e84adb 100644
--- a/docs/reference/interfaces/SequenceOptions.md
+++ b/docs/reference/interfaces/HotkeySequenceOptions.md
@@ -1,26 +1,41 @@
---
-id: SequenceOptions
-title: SequenceOptions
+id: HotkeySequenceOptions
+title: HotkeySequenceOptions
---
-Defined in: [sequence-manager.ts:31](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L31)
+Defined in: [hotkey-manager.ts:79](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L79)
-Options for hotkey sequence matching.
-Extends HotkeyOptions but excludes requireReset (not applicable to sequences).
+Options for a sequence such as `['G', 'G']`.
## Extends
-- `Omit`\<[`HotkeyOptions`](HotkeyOptions.md), `"requireReset"`\>
+- [`HotkeyOptions`](HotkeyOptions.md)
## Properties
+### appHotkeyId?
+
+```ts
+optional appHotkeyId?: string;
+```
+
+Defined in: [hotkey-manager.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L69)
+
+Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`.
+
+#### Inherited from
+
+[`HotkeyOptions`](HotkeyOptions.md).[`appHotkeyId`](HotkeyOptions.md#apphotkeyid)
+
+***
+
### conflictBehavior?
```ts
optional conflictBehavior?: ConflictBehavior;
```
-Defined in: [hotkey-manager.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L33)
+Defined in: [hotkey-manager.ts:47](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L47)
Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn'
@@ -36,7 +51,7 @@ Behavior when this hotkey conflicts with an existing registration on the same ta
optional enabled?: boolean;
```
-Defined in: [hotkey-manager.ts:39](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L39)
+Defined in: [hotkey-manager.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L53)
Soft-disable: when `false`, the callback does not run but the registration
stays in `HotkeyManager` (and in devtools). Toggling this should update the
@@ -54,7 +69,7 @@ existing handle via `setOptions` rather than unregistering. Defaults to `true`.
optional eventType?: "keyup" | "keydown";
```
-Defined in: [hotkey-manager.ts:41](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L41)
+Defined in: [hotkey-manager.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L55)
The event type to listen for. Defaults to 'keydown'
@@ -70,9 +85,9 @@ The event type to listen for. Defaults to 'keydown'
optional ignoreInputs?: boolean;
```
-Defined in: [hotkey-manager.ts:43](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L43)
+Defined in: [hotkey-manager.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L57)
-Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape
+Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on the hotkey (the first step of a sequence): true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape
#### Inherited from
@@ -86,7 +101,7 @@ Whether to ignore hotkeys when keyboard events originate from input-like element
optional meta?: HotkeyMeta;
```
-Defined in: [hotkey-manager.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L55)
+Defined in: [hotkey-manager.ts:67](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L67)
Optional metadata (name, description, custom fields via declaration merging)
@@ -102,7 +117,7 @@ Optional metadata (name, description, custom fields via declaration merging)
optional platform?: "mac" | "windows" | "linux";
```
-Defined in: [hotkey-manager.ts:45](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L45)
+Defined in: [hotkey-manager.ts:59](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L59)
The target platform for resolving 'Mod'
@@ -118,7 +133,7 @@ The target platform for resolving 'Mod'
optional preventDefault?: boolean;
```
-Defined in: [hotkey-manager.ts:47](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L47)
+Defined in: [hotkey-manager.ts:61](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L61)
Prevent the default browser action when the hotkey matches. Defaults to true
@@ -134,7 +149,7 @@ Prevent the default browser action when the hotkey matches. Defaults to true
optional stopPropagation?: boolean;
```
-Defined in: [hotkey-manager.ts:51](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L51)
+Defined in: [hotkey-manager.ts:63](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L63)
Stop event propagation when the hotkey matches. Defaults to true
@@ -147,10 +162,10 @@ Stop event propagation when the hotkey matches. Defaults to true
### target?
```ts
-optional target?: Document | Window | HTMLElement | null;
+optional target?: Target | null;
```
-Defined in: [hotkey-manager.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L53)
+Defined in: [hotkey-manager.ts:65](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L65)
The DOM element to attach the event listener to. Defaults to document.
@@ -166,6 +181,6 @@ The DOM element to attach the event listener to. Defaults to document.
optional timeout?: number;
```
-Defined in: [sequence-manager.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L33)
+Defined in: [hotkey-manager.ts:81](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L81)
-Timeout between keys in milliseconds. Default: 1000
+Maximum time between steps in milliseconds. Default: 1000
diff --git a/docs/reference/interfaces/HotkeySequenceRecorderOptions.md b/docs/reference/interfaces/HotkeySequenceRecorderOptions.md
index b117454a..1da3f77f 100644
--- a/docs/reference/interfaces/HotkeySequenceRecorderOptions.md
+++ b/docs/reference/interfaces/HotkeySequenceRecorderOptions.md
@@ -3,49 +3,26 @@ id: HotkeySequenceRecorderOptions
title: HotkeySequenceRecorderOptions
---
-Defined in: [hotkey-sequence-recorder.ts:42](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L42)
+Defined in: [hotkey-recorder.ts:69](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L69)
-Options for configuring a HotkeySequenceRecorder instance.
+Options for recording up to `maxSteps` chords. A one-step recording commits
+as a chord string; two or more steps commit as a sequence.
## Extends
-- [`RecorderOptions`](RecorderOptions.md)
+- `HotkeyRecorderBaseOptions`
## Properties
### commitKeys?
```ts
-optional commitKeys?: HotkeySequenceRecorderCommitKeys;
+optional commitKeys?: HotkeyRecorderCommitKeys;
```
-Defined in: [hotkey-sequence-recorder.ts:63](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L63)
+Defined in: [hotkey-recorder.ts:80](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L80)
-Keyboard commit mode. When `'none'`, use [HotkeySequenceRecorder.commit](../classes/HotkeySequenceRecorder.md#commit) (and optional idle timeout).
-
-#### Default
-
-```ts
-'enter'
-```
-
-***
-
-### commitOnEnter?
-
-```ts
-optional commitOnEnter?: boolean;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:58](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L58)
-
-Whether plain Enter commits the current steps. Ignored when [commitKeys](#commitkeys) is `'none'`.
-
-#### Default
-
-```ts
-true
-```
+Whether plain Enter commits the recorded steps. Default: 'enter'
***
@@ -61,7 +38,9 @@ Opt in to live-registry conflicts, including sequence prefixes. Default: false.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`detectConflicts`](RecorderOptions.md#detectconflicts)
+```ts
+HotkeyRecorderBaseOptions.detectConflicts
+```
***
@@ -71,10 +50,9 @@ Opt in to live-registry conflicts, including sequence prefixes. Default: false.
optional idleTimeoutMs?: number;
```
-Defined in: [hotkey-sequence-recorder.ts:68](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L68)
+Defined in: [hotkey-recorder.ts:82](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L82)
-Milliseconds of inactivity after the **last completed chord** before auto-committing.
-The timer does not run while waiting for the first chord (`steps.length === 0`).
+Commit automatically after this many milliseconds without a new step. Disabled when unset or 0.
***
@@ -84,28 +62,39 @@ The timer does not run while waiting for the first chord (`steps.length === 0`).
optional ignoreInputs?: boolean;
```
-Defined in: [hotkey-sequence-recorder.ts:76](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L76)
+Defined in: [hotkey-recorder.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L49)
Whether to ignore keyboard events from input-like elements (text inputs,
-textarea, select, contenteditable). When true, typing in inputs passes
-through normally instead of being captured as a sequence recording.
-Escape always works regardless of this setting.
+textarea, select, contenteditable) while recording. When true, typing in
+inputs passes through normally (Escape still cancels). Defaults to true.
-#### Default
+#### Inherited from
```ts
-true
+HotkeyRecorderBaseOptions.ignoreInputs
```
***
+### maxSteps
+
+```ts
+maxSteps: number;
+```
+
+Defined in: [hotkey-recorder.ts:71](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L71)
+
+Maximum number of chords to record. Reaching it commits automatically. Use `Infinity` for no limit.
+
+***
+
### onCancel?
```ts
optional onCancel?: () => void;
```
-Defined in: [hotkey-sequence-recorder.ts:51](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L51)
+Defined in: [hotkey-recorder.ts:38](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L38)
Optional callback when recording is cancelled (Escape pressed)
@@ -113,6 +102,12 @@ Optional callback when recording is cancelled (Escape pressed)
`void`
+#### Inherited from
+
+```ts
+HotkeyRecorderBaseOptions.onCancel
+```
+
***
### onClear?
@@ -121,31 +116,38 @@ Optional callback when recording is cancelled (Escape pressed)
optional onClear?: () => void;
```
-Defined in: [hotkey-sequence-recorder.ts:53](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L53)
+Defined in: [hotkey-recorder.ts:43](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L43)
-Optional callback when the sequence is cleared (Backspace/Delete with no steps)
+Optional callback when the recording is cleared: Backspace/Delete with no
+modifiers and no recorded steps
#### Returns
`void`
+#### Inherited from
+
+```ts
+HotkeyRecorderBaseOptions.onClear
+```
+
***
### onRecord
```ts
-onRecord: (sequence) => void;
+onRecord: (hotkey) => void;
```
-Defined in: [hotkey-sequence-recorder.ts:49](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L49)
+Defined in: [hotkey-recorder.ts:78](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L78)
-Callback when a sequence is successfully recorded
+Callback when a hotkey is successfully recorded
#### Parameters
-##### sequence
+##### hotkey
-[`HotkeySequence`](../type-aliases/HotkeySequence.md)
+[`Hotkey`](../type-aliases/Hotkey.md)
#### Returns
@@ -175,7 +177,9 @@ Rejected candidates leave recording active.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`onReject`](RecorderOptions.md#onreject)
+```ts
+HotkeyRecorderBaseOptions.onReject
+```
***
@@ -191,7 +195,9 @@ Platform used for Mod and AltGraph handling. Defaults to platform detection.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`platform`](RecorderOptions.md#platform)
+```ts
+HotkeyRecorderBaseOptions.platform
+```
***
@@ -207,29 +213,31 @@ Physical code recording is the default. Choose key to record logical characters.
#### Inherited from
-[`RecorderOptions`](RecorderOptions.md).[`recordBy`](RecorderOptions.md#recordby)
+```ts
+HotkeyRecorderBaseOptions.recordBy
+```
***
### validate?
```ts
-optional validate?: (sequence, context) => string | boolean;
+optional validate?: (hotkey, context) => string | boolean;
```
-Defined in: [hotkey-sequence-recorder.ts:44](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L44)
+Defined in: [hotkey-recorder.ts:73](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L73)
-Validate the completed sequence. Rejection preserves the steps for editing.
+Return true to accept, or false/a message to reject while staying in recording mode.
#### Parameters
-##### sequence
+##### hotkey
-[`HotkeySequence`](../type-aliases/HotkeySequence.md)
+[`Hotkey`](../type-aliases/Hotkey.md)
##### context
-[`HotkeySequenceRecorderValidationContext`](HotkeySequenceRecorderValidationContext.md)
+[`HotkeyRecorderValidationContext`](HotkeyRecorderValidationContext.md)
#### Returns
diff --git a/docs/reference/interfaces/HotkeySequenceRecorderState.md b/docs/reference/interfaces/HotkeySequenceRecorderState.md
deleted file mode 100644
index 9e92d0f7..00000000
--- a/docs/reference/interfaces/HotkeySequenceRecorderState.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-id: HotkeySequenceRecorderState
-title: HotkeySequenceRecorderState
----
-
-Defined in: [hotkey-sequence-recorder.ts:30](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L30)
-
-State interface for the HotkeySequenceRecorder.
-
-## Properties
-
-### isRecording
-
-```ts
-isRecording: boolean;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:32](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L32)
-
-Whether recording is currently active
-
-***
-
-### recordedSequence
-
-```ts
-recordedSequence: HotkeySequence | null;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:36](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L36)
-
-The last successfully committed sequence, or null if none / after starting a new session
-
-***
-
-### steps
-
-```ts
-steps: HotkeySequence;
-```
-
-Defined in: [hotkey-sequence-recorder.ts:34](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L34)
-
-Chords captured so far in the current recording session
diff --git a/docs/reference/interfaces/HotkeySequenceRecorderValidationContext.md b/docs/reference/interfaces/HotkeySequenceRecorderValidationContext.md
deleted file mode 100644
index 637ad067..00000000
--- a/docs/reference/interfaces/HotkeySequenceRecorderValidationContext.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-id: HotkeySequenceRecorderValidationContext
-title: HotkeySequenceRecorderValidationContext
----
-
-Defined in: [recorder-options.ts:31](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L31)
-
-## Properties
-
-### events
-
-```ts
-events: readonly KeyboardEvent[];
-```
-
-Defined in: [recorder-options.ts:32](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L32)
-
-***
-
-### parsedSequence
-
-```ts
-parsedSequence: readonly ParsedHotkey[];
-```
-
-Defined in: [recorder-options.ts:33](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L33)
diff --git a/docs/reference/interfaces/HotkeySequenceRegistration.md b/docs/reference/interfaces/HotkeySequenceRegistration.md
new file mode 100644
index 00000000..4172c30e
--- /dev/null
+++ b/docs/reference/interfaces/HotkeySequenceRegistration.md
@@ -0,0 +1,174 @@
+---
+id: HotkeySequenceRegistration
+title: HotkeySequenceRegistration
+---
+
+Defined in: [hotkey-manager.ts:121](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L121)
+
+A registered sequence in the HotkeyManager.
+
+## Extends
+
+- `RegistrationBase`\<[`HotkeySequenceOptions`](HotkeySequenceOptions.md)\>
+
+## Properties
+
+### callback
+
+```ts
+callback: HotkeyCallback;
+```
+
+Defined in: [hotkey-manager.ts:100](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L100)
+
+The callback to invoke
+
+#### Inherited from
+
+```ts
+RegistrationBase.callback
+```
+
+***
+
+### currentIndex
+
+```ts
+currentIndex: number;
+```
+
+Defined in: [hotkey-manager.ts:126](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L126)
+
+Steps matched in the current attempt
+
+***
+
+### hasFired
+
+```ts
+hasFired: boolean;
+```
+
+Defined in: [hotkey-manager.ts:108](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L108)
+
+Whether this registration has fired (and, for requireReset chords, needs a reset)
+
+#### Inherited from
+
+```ts
+RegistrationBase.hasFired
+```
+
+***
+
+### hotkey
+
+```ts
+hotkey: HotkeySequence;
+```
+
+Defined in: [hotkey-manager.ts:123](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L123)
+
+***
+
+### id
+
+```ts
+id: string;
+```
+
+Defined in: [hotkey-manager.ts:98](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L98)
+
+Unique identifier for this registration
+
+#### Inherited from
+
+```ts
+RegistrationBase.id
+```
+
+***
+
+### kind
+
+```ts
+kind: "sequence";
+```
+
+Defined in: [hotkey-manager.ts:122](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L122)
+
+***
+
+### lastKeyTime
+
+```ts
+lastKeyTime: number;
+```
+
+Defined in: [hotkey-manager.ts:128](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L128)
+
+`Date.now()` when the last step in the current attempt matched
+
+***
+
+### options
+
+```ts
+options: HotkeySequenceOptions;
+```
+
+Defined in: [hotkey-manager.ts:102](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L102)
+
+Resolved options for this registration
+
+#### Inherited from
+
+```ts
+RegistrationBase.options
+```
+
+***
+
+### parsedSequence
+
+```ts
+parsedSequence: ParsedHotkey[];
+```
+
+Defined in: [hotkey-manager.ts:124](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L124)
+
+***
+
+### target
+
+```ts
+target: Target;
+```
+
+Defined in: [hotkey-manager.ts:104](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L104)
+
+The resolved target element for this registration
+
+#### Inherited from
+
+```ts
+RegistrationBase.target
+```
+
+***
+
+### triggerCount
+
+```ts
+triggerCount: number;
+```
+
+Defined in: [hotkey-manager.ts:106](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L106)
+
+How many times this registration's callback has been triggered
+
+#### Inherited from
+
+```ts
+RegistrationBase.triggerCount
+```
diff --git a/docs/reference/interfaces/HotkeySequenceRegistrationView.md b/docs/reference/interfaces/HotkeySequenceRegistrationView.md
new file mode 100644
index 00000000..d2fb66a9
--- /dev/null
+++ b/docs/reference/interfaces/HotkeySequenceRegistrationView.md
@@ -0,0 +1,140 @@
+---
+id: HotkeySequenceRegistrationView
+title: HotkeySequenceRegistrationView
+---
+
+Defined in: [hotkey-manager.ts:151](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L151)
+
+Public view of a sequence registration, without its callback.
+
+## Extends
+
+- `RegistrationViewBase`
+
+## Properties
+
+### hasFired
+
+```ts
+hasFired: boolean;
+```
+
+Defined in: [hotkey-manager.ts:139](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L139)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.hasFired
+```
+
+***
+
+### hotkey
+
+```ts
+hotkey: HotkeySequence;
+```
+
+Defined in: [hotkey-manager.ts:153](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L153)
+
+***
+
+### id
+
+```ts
+id: string;
+```
+
+Defined in: [hotkey-manager.ts:136](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L136)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.id
+```
+
+***
+
+### kind
+
+```ts
+kind: "sequence";
+```
+
+Defined in: [hotkey-manager.ts:152](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L152)
+
+***
+
+### matchedStepCount
+
+```ts
+matchedStepCount: number;
+```
+
+Defined in: [hotkey-manager.ts:157](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L157)
+
+Steps matched in the current attempt (0 when idle or just completed).
+
+***
+
+### options
+
+```ts
+options: HotkeySequenceOptions;
+```
+
+Defined in: [hotkey-manager.ts:155](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L155)
+
+***
+
+### parsedSequence
+
+```ts
+parsedSequence: ParsedHotkey[];
+```
+
+Defined in: [hotkey-manager.ts:154](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L154)
+
+***
+
+### partialMatchLastKeyTime
+
+```ts
+partialMatchLastKeyTime: number;
+```
+
+Defined in: [hotkey-manager.ts:159](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L159)
+
+`Date.now()` when the last step in the current attempt matched; 0 if none.
+
+***
+
+### target
+
+```ts
+target: Target;
+```
+
+Defined in: [hotkey-manager.ts:137](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L137)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.target
+```
+
+***
+
+### triggerCount
+
+```ts
+triggerCount: number;
+```
+
+Defined in: [hotkey-manager.ts:138](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L138)
+
+#### Inherited from
+
+```ts
+RegistrationViewBase.triggerCount
+```
diff --git a/docs/reference/interfaces/KeyboardEventMatch.md b/docs/reference/interfaces/KeyboardEventMatch.md
index 3ac18665..3e3a1b1d 100644
--- a/docs/reference/interfaces/KeyboardEventMatch.md
+++ b/docs/reference/interfaces/KeyboardEventMatch.md
@@ -3,7 +3,7 @@ id: KeyboardEventMatch
title: KeyboardEventMatch
---
-Defined in: [match.ts:13](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L13)
+Defined in: [match.ts:21](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L21)
## Properties
@@ -13,7 +13,7 @@ Defined in: [match.ts:13](https://github.com/TanStack/hotkeys/blob/main/packages
optional identity?: object;
```
-Defined in: [match.ts:17](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L17)
+Defined in: [match.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L25)
#### code
@@ -35,7 +35,7 @@ key: string;
matched: boolean;
```
-Defined in: [match.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L14)
+Defined in: [match.ts:22](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L22)
***
@@ -45,7 +45,7 @@ Defined in: [match.ts:14](https://github.com/TanStack/hotkeys/blob/main/packages
score: 0 | 1 | 2 | 3;
```
-Defined in: [match.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L15)
+Defined in: [match.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L23)
***
@@ -55,4 +55,4 @@ Defined in: [match.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages
optional source?: "key" | "code" | "fallback";
```
-Defined in: [match.ts:16](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L16)
+Defined in: [match.ts:24](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L24)
diff --git a/docs/reference/interfaces/RecorderOptions.md b/docs/reference/interfaces/RecorderOptions.md
index 33f006f8..6cf99fe9 100644
--- a/docs/reference/interfaces/RecorderOptions.md
+++ b/docs/reference/interfaces/RecorderOptions.md
@@ -5,11 +5,6 @@ title: RecorderOptions
Defined in: [recorder-options.ts:15](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L15)
-## Extended by
-
-- [`HotkeyRecorderOptions`](HotkeyRecorderOptions.md)
-- [`HotkeySequenceRecorderOptions`](HotkeySequenceRecorderOptions.md)
-
## Properties
### detectConflicts?
diff --git a/docs/reference/interfaces/RecorderRejection.md b/docs/reference/interfaces/RecorderRejection.md
index 71091854..93f9aa32 100644
--- a/docs/reference/interfaces/RecorderRejection.md
+++ b/docs/reference/interfaces/RecorderRejection.md
@@ -23,7 +23,9 @@ Defined in: [recorder-options.ts:12](https://github.com/TanStack/hotkeys/blob/ma
optional hotkey?: Hotkey;
```
-Defined in: [recorder-options.ts:10](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L10)
+Defined in: [recorder-options.ts:11](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L11)
+
+The rejected chord or sequence, when one was recorded.
***
@@ -44,13 +46,3 @@ reason: "invalid" | "missing-code" | "alt-graph" | "conflict" | "validation";
```
Defined in: [recorder-options.ts:8](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L8)
-
-***
-
-### sequence?
-
-```ts
-optional sequence?: Hotkey[];
-```
-
-Defined in: [recorder-options.ts:11](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/recorder-options.ts#L11)
diff --git a/docs/reference/interfaces/Register.md b/docs/reference/interfaces/Register.md
new file mode 100644
index 00000000..1031cbe7
--- /dev/null
+++ b/docs/reference/interfaces/Register.md
@@ -0,0 +1,18 @@
+---
+id: Register
+title: Register
+---
+
+Defined in: [app-hotkeys.ts:141](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L141)
+
+Register your app hotkeys to type `useAppHotkeys()` and `CustomHotkeys`.
+
+## Example
+
+```ts
+declare module '@tanstack/react-hotkeys' {
+ interface Register {
+ appHotkeys: typeof appHotkeys
+ }
+}
+```
diff --git a/docs/reference/interfaces/SequenceRegistration.md b/docs/reference/interfaces/SequenceRegistration.md
deleted file mode 100644
index 6a8b439e..00000000
--- a/docs/reference/interfaces/SequenceRegistration.md
+++ /dev/null
@@ -1,108 +0,0 @@
----
-id: SequenceRegistration
-title: SequenceRegistration
----
-
-Defined in: [sequence-manager.ts:90](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L90)
-
-Internal representation of a sequence registration.
-
-## Properties
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [sequence-manager.ts:94](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L94)
-
-***
-
-### currentIndex
-
-```ts
-currentIndex: number;
-```
-
-Defined in: [sequence-manager.ts:97](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L97)
-
-***
-
-### hasFired
-
-```ts
-hasFired: boolean;
-```
-
-Defined in: [sequence-manager.ts:100](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L100)
-
-***
-
-### id
-
-```ts
-id: string;
-```
-
-Defined in: [sequence-manager.ts:91](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L91)
-
-***
-
-### lastKeyTime
-
-```ts
-lastKeyTime: number;
-```
-
-Defined in: [sequence-manager.ts:98](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L98)
-
-***
-
-### options
-
-```ts
-options: SequenceOptions;
-```
-
-Defined in: [sequence-manager.ts:95](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L95)
-
-***
-
-### parsedSequence
-
-```ts
-parsedSequence: ParsedHotkey[];
-```
-
-Defined in: [sequence-manager.ts:93](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L93)
-
-***
-
-### sequence
-
-```ts
-sequence: HotkeySequence;
-```
-
-Defined in: [sequence-manager.ts:92](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L92)
-
-***
-
-### target
-
-```ts
-target: Target;
-```
-
-Defined in: [sequence-manager.ts:96](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L96)
-
-***
-
-### triggerCount
-
-```ts
-triggerCount: number;
-```
-
-Defined in: [sequence-manager.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L99)
diff --git a/docs/reference/interfaces/SequenceRegistrationHandle.md b/docs/reference/interfaces/SequenceRegistrationHandle.md
deleted file mode 100644
index 58a79ea7..00000000
--- a/docs/reference/interfaces/SequenceRegistrationHandle.md
+++ /dev/null
@@ -1,83 +0,0 @@
----
-id: SequenceRegistrationHandle
-title: SequenceRegistrationHandle
----
-
-Defined in: [sequence-manager.ts:116](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L116)
-
-A handle returned from SequenceManager.register() that allows updating
-the callback and options without re-registering the sequence.
-
-## Example
-
-```ts
-const handle = manager.register(['G', 'G'], callback, options)
-
-handle.callback = newCallback
-handle.setOptions({ timeout: 500 })
-handle.unregister()
-```
-
-## Properties
-
-### callback
-
-```ts
-callback: HotkeyCallback;
-```
-
-Defined in: [sequence-manager.ts:119](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L119)
-
-***
-
-### id
-
-```ts
-readonly id: string;
-```
-
-Defined in: [sequence-manager.ts:117](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L117)
-
-***
-
-### isActive
-
-```ts
-readonly isActive: boolean;
-```
-
-Defined in: [sequence-manager.ts:118](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L118)
-
-***
-
-### setOptions
-
-```ts
-setOptions: (options) => void;
-```
-
-Defined in: [sequence-manager.ts:120](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L120)
-
-#### Parameters
-
-##### options
-
-`Partial`\<[`SequenceOptions`](SequenceOptions.md)\>
-
-#### Returns
-
-`void`
-
-***
-
-### unregister
-
-```ts
-unregister: () => void;
-```
-
-Defined in: [sequence-manager.ts:121](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L121)
-
-#### Returns
-
-`void`
diff --git a/docs/reference/interfaces/SequenceRegistrationView.md b/docs/reference/interfaces/SequenceRegistrationView.md
deleted file mode 100644
index ce29b3ea..00000000
--- a/docs/reference/interfaces/SequenceRegistrationView.md
+++ /dev/null
@@ -1,95 +0,0 @@
----
-id: SequenceRegistrationView
-title: SequenceRegistrationView
----
-
-Defined in: [sequence-manager.ts:73](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L73)
-
-View of a sequence registration for devtools display.
-Progress fields reflect an in-progress match (between first key and completion or timeout).
-
-## Properties
-
-### hasFired
-
-```ts
-hasFired: boolean;
-```
-
-Defined in: [sequence-manager.ts:80](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L80)
-
-Whether this sequence has been triggered at least once.
-
-***
-
-### id
-
-```ts
-id: string;
-```
-
-Defined in: [sequence-manager.ts:74](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L74)
-
-***
-
-### matchedStepCount
-
-```ts
-matchedStepCount: number;
-```
-
-Defined in: [sequence-manager.ts:82](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L82)
-
-Steps matched in the current attempt (0 when idle or just completed).
-
-***
-
-### options
-
-```ts
-options: SequenceOptions;
-```
-
-Defined in: [sequence-manager.ts:76](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L76)
-
-***
-
-### partialMatchLastKeyTime
-
-```ts
-partialMatchLastKeyTime: number;
-```
-
-Defined in: [sequence-manager.ts:84](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L84)
-
-`Date.now()` when the last step in the current attempt matched; 0 if none.
-
-***
-
-### sequence
-
-```ts
-sequence: HotkeySequence;
-```
-
-Defined in: [sequence-manager.ts:75](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L75)
-
-***
-
-### target
-
-```ts
-target: Target;
-```
-
-Defined in: [sequence-manager.ts:77](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L77)
-
-***
-
-### triggerCount
-
-```ts
-triggerCount: number;
-```
-
-Defined in: [sequence-manager.ts:78](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L78)
diff --git a/docs/reference/interfaces/ValidationResult.md b/docs/reference/interfaces/ValidationResult.md
index 25155b75..7c156e5c 100644
--- a/docs/reference/interfaces/ValidationResult.md
+++ b/docs/reference/interfaces/ValidationResult.md
@@ -3,7 +3,7 @@ id: ValidationResult
title: ValidationResult
---
-Defined in: [validate.ts:172](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L172)
+Defined in: [validate.ts:209](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L209)
Result of validating a hotkey string.
@@ -15,7 +15,7 @@ Result of validating a hotkey string.
errors: string[];
```
-Defined in: [validate.ts:178](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L178)
+Defined in: [validate.ts:215](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L215)
Error messages about invalid syntax
@@ -27,7 +27,7 @@ Error messages about invalid syntax
valid: boolean;
```
-Defined in: [validate.ts:174](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L174)
+Defined in: [validate.ts:211](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L211)
Whether the hotkey is valid (can still have warnings)
@@ -39,6 +39,6 @@ Whether the hotkey is valid (can still have warnings)
warnings: string[];
```
-Defined in: [validate.ts:176](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L176)
+Defined in: [validate.ts:213](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L213)
Warning messages about potential issues
diff --git a/docs/reference/type-aliases/AppHotkeyChordOptions.md b/docs/reference/type-aliases/AppHotkeyChordOptions.md
new file mode 100644
index 00000000..121c258c
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeyChordOptions.md
@@ -0,0 +1,12 @@
+---
+id: AppHotkeyChordOptions
+title: AppHotkeyChordOptions
+---
+
+```ts
+type AppHotkeyChordOptions = Pick;
+```
+
+Defined in: [app-hotkeys.ts:29](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L29)
+
+Declared options for an app hotkey whose default is a chord.
diff --git a/docs/reference/type-aliases/AppHotkeyDefaultKind.md b/docs/reference/type-aliases/AppHotkeyDefaultKind.md
new file mode 100644
index 00000000..9f6a4b84
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeyDefaultKind.md
@@ -0,0 +1,18 @@
+---
+id: AppHotkeyDefaultKind
+title: AppHotkeyDefaultKind
+---
+
+```ts
+type AppHotkeyDefaultKind = THotkey extends null ? null : THotkey extends readonly [unknown] ? HotkeyChord : THotkey extends ReadonlyArray ? HotkeySequence : HotkeyChord;
+```
+
+Defined in: [app-hotkeys.ts:113](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L113)
+
+The kind of a declared default hotkey; a one-step sequence is a chord.
+
+## Type Parameters
+
+### THotkey
+
+`THotkey`
diff --git a/docs/reference/type-aliases/AppHotkeyId.md b/docs/reference/type-aliases/AppHotkeyId.md
new file mode 100644
index 00000000..184796f0
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeyId.md
@@ -0,0 +1,12 @@
+---
+id: AppHotkeyId
+title: AppHotkeyId
+---
+
+```ts
+type AppHotkeyId = keyof RegisteredAppHotkeys & string;
+```
+
+Defined in: [app-hotkeys.ts:151](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L151)
+
+Ids of the registered app hotkeys.
diff --git a/docs/reference/type-aliases/AppHotkeyOptions.md b/docs/reference/type-aliases/AppHotkeyOptions.md
new file mode 100644
index 00000000..d82a2e99
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeyOptions.md
@@ -0,0 +1,12 @@
+---
+id: AppHotkeyOptions
+title: AppHotkeyOptions
+---
+
+```ts
+type AppHotkeyOptions = AppHotkeyChordOptions & AppHotkeySequenceOptions;
+```
+
+Defined in: [app-hotkeys.ts:41](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L41)
+
+Every declared option. Kind-specific options apply only while the effective hotkey has that kind.
diff --git a/docs/reference/type-aliases/AppHotkeySequenceOptions.md b/docs/reference/type-aliases/AppHotkeySequenceOptions.md
new file mode 100644
index 00000000..74148ba8
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeySequenceOptions.md
@@ -0,0 +1,12 @@
+---
+id: AppHotkeySequenceOptions
+title: AppHotkeySequenceOptions
+---
+
+```ts
+type AppHotkeySequenceOptions = Pick;
+```
+
+Defined in: [app-hotkeys.ts:35](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L35)
+
+Declared options for an app hotkey whose default is a sequence.
diff --git a/docs/reference/type-aliases/AppHotkeyStatus.md b/docs/reference/type-aliases/AppHotkeyStatus.md
new file mode 100644
index 00000000..2b42dfd5
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeyStatus.md
@@ -0,0 +1,16 @@
+---
+id: AppHotkeyStatus
+title: AppHotkeyStatus
+---
+
+```ts
+type AppHotkeyStatus = "active" | "disabled" | "inactive" | "unbound";
+```
+
+Defined in: [app-hotkeys.ts:304](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L304)
+
+Status of an app hotkey in the running app.
+- `'active'`: at least one enabled registration
+- `'disabled'`: registered, but every registration has `enabled: false`
+- `'inactive'`: has a hotkey, but nothing has registered it
+- `'unbound'`: no hotkey assigned
diff --git a/docs/reference/type-aliases/AppHotkeys.md b/docs/reference/type-aliases/AppHotkeys.md
new file mode 100644
index 00000000..cf0cc31d
--- /dev/null
+++ b/docs/reference/type-aliases/AppHotkeys.md
@@ -0,0 +1,12 @@
+---
+id: AppHotkeys
+title: AppHotkeys
+---
+
+```ts
+type AppHotkeys = Readonly>;
+```
+
+Defined in: [app-hotkeys.ts:88](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L88)
+
+A map of app hotkeys keyed by id.
diff --git a/docs/reference/type-aliases/ConflictBehavior.md b/docs/reference/type-aliases/ConflictBehavior.md
index 29c22f77..68d92535 100644
--- a/docs/reference/type-aliases/ConflictBehavior.md
+++ b/docs/reference/type-aliases/ConflictBehavior.md
@@ -7,7 +7,7 @@ title: ConflictBehavior
type ConflictBehavior = "warn" | "error" | "replace" | "allow";
```
-Defined in: [hotkey.types.ts:269](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L269)
+Defined in: [hotkey.types.ts:286](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L286)
Behavior when registering a hotkey/sequence that conflicts with an existing registration.
diff --git a/docs/reference/type-aliases/CustomHotkeys.md b/docs/reference/type-aliases/CustomHotkeys.md
new file mode 100644
index 00000000..59124f12
--- /dev/null
+++ b/docs/reference/type-aliases/CustomHotkeys.md
@@ -0,0 +1,19 @@
+---
+id: CustomHotkeys
+title: CustomHotkeys
+---
+
+```ts
+type CustomHotkeys = { -readonly [K in keyof T]?: Hotkey | null };
+```
+
+Defined in: [app-hotkeys.ts:157](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L157)
+
+The user's hotkeys that differ from the declared defaults, keyed by app
+hotkey id. This is the shape to save. `null` means the user unbound it.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`AppHotkeys`](AppHotkeys.md) = [`RegisteredAppHotkeys`](RegisteredAppHotkeys.md)
diff --git a/docs/reference/type-aliases/DefinedAppHotkeys.md b/docs/reference/type-aliases/DefinedAppHotkeys.md
new file mode 100644
index 00000000..62306b1d
--- /dev/null
+++ b/docs/reference/type-aliases/DefinedAppHotkeys.md
@@ -0,0 +1,18 @@
+---
+id: DefinedAppHotkeys
+title: DefinedAppHotkeys
+---
+
+```ts
+type DefinedAppHotkeys = { readonly [K in keyof T & string]: AppHotkey> };
+```
+
+Defined in: [app-hotkeys.ts:122](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L122)
+
+The app hotkeys returned by `defineAppHotkeys` for a declaration object.
+
+## Type Parameters
+
+### T
+
+`T` *extends* `Record`\<`string`, [`AppHotkeyInput`](../interfaces/AppHotkeyInput.md)\>
diff --git a/docs/reference/type-aliases/DisplayHotkey.md b/docs/reference/type-aliases/DisplayHotkey.md
index fde7a023..82b21b1d 100644
--- a/docs/reference/type-aliases/DisplayHotkey.md
+++ b/docs/reference/type-aliases/DisplayHotkey.md
@@ -5,9 +5,10 @@ title: DisplayHotkey
```ts
type DisplayHotkey =
- | RegisterableHotkey
- | ParsedHotkey
- | string & object;
+ | DisplayHotkeyChord
+| ReadonlyArray;
```
-Defined in: [format.ts:71](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L71)
+Defined in: [format.ts:59](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L59)
+
+A hotkey to display: a chord or a sequence of chords.
diff --git a/docs/reference/type-aliases/DisplayHotkeyChord.md b/docs/reference/type-aliases/DisplayHotkeyChord.md
new file mode 100644
index 00000000..7c14faa1
--- /dev/null
+++ b/docs/reference/type-aliases/DisplayHotkeyChord.md
@@ -0,0 +1,15 @@
+---
+id: DisplayHotkeyChord
+title: DisplayHotkeyChord
+---
+
+```ts
+type DisplayHotkeyChord =
+ | RegisterableHotkeyChord
+ | ParsedHotkey
+ | string & object;
+```
+
+Defined in: [format.ts:55](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L55)
+
+A single chord to display: a string, raw object, or parsed hotkey.
diff --git a/docs/reference/type-aliases/Hotkey.md b/docs/reference/type-aliases/Hotkey.md
index 7b0d1087..62b7e93e 100644
--- a/docs/reference/type-aliases/Hotkey.md
+++ b/docs/reference/type-aliases/Hotkey.md
@@ -4,64 +4,9 @@ title: Hotkey
---
```ts
-type Hotkey =
- | Key
- | SingleModifierHotkey
- | TwoModifierHotkey
- | ThreeModifierHotkey
- | FourModifierHotkey;
+type Hotkey = HotkeyChord | HotkeySequence;
```
-Defined in: [hotkey.types.ts:126](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L126)
+Defined in: [hotkey.types.ts:216](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L216)
-A type-safe hotkey string.
-
-Provides autocomplete for:
-- All single keys (letters, numbers, function keys, navigation, editing, punctuation)
-- Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
-- Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
-- Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
-- Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)
-
-## Modifier Names
-
-Use canonical modifier names:
-- `Control` (not Ctrl) - The Control key
-- `Alt` (not Option) - The Alt key (Option on macOS)
-- `Meta` (not Command/Cmd) - The Meta/Command key (macOS only)
-- `Shift` - The Shift key
-
-## Platform-Adaptive `Mod` Modifier
-
-The `Mod` modifier is a special platform-adaptive modifier that automatically resolves
-to the "primary modifier" on each platform:
-
-- **macOS**: `Mod` → `Meta` (Command key ⌘)
-- **Windows/Linux**: `Mod` → `Control` (Ctrl key)
-
-This enables cross-platform hotkey definitions that work correctly on all platforms
-without platform-specific code. The `Mod` modifier is resolved at runtime based on
-the detected platform.
-
-**When to use `Mod` vs platform-specific modifiers:**
-- Use `Mod` for cross-platform shortcuts (e.g., `Mod+S` for save)
-- Use `Meta` or `Control` when you need platform-specific behavior
-- Use `Mod` when you want your shortcuts to follow platform conventions automatically
-
-**Limitations:**
-- `Mod+Control` and `Mod+Meta` combinations are not allowed (they create duplicate
- modifiers on one platform)
-- In four-modifier combinations, only canonical modifiers are allowed (no `Mod`)
-
-## Example
-
-```ts
-// Cross-platform shortcuts (recommended)
-const save: Hotkey = 'Mod+S' // Command+S on Mac, Ctrl+S on Windows/Linux
-const saveAs: Hotkey = 'Mod+Shift+S' // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
-const comment: Hotkey = 'Mod+/' // Command+/ on Mac, Ctrl+/ elsewhere
-
-// Platform-specific shortcuts
-const macOnly: Hotkey = 'Meta+S' // Command+S on Mac only
-const windowsOnly: Hotkey = 'Control+S' // Ctrl+S on Windows/Linux only
-```
+A hotkey: one chord (`'Mod+S'`) or a sequence of chords (`['G', 'G']`).
diff --git a/docs/reference/type-aliases/HotkeyCallback.md b/docs/reference/type-aliases/HotkeyCallback.md
index c2d272be..44c9700b 100644
--- a/docs/reference/type-aliases/HotkeyCallback.md
+++ b/docs/reference/type-aliases/HotkeyCallback.md
@@ -7,7 +7,7 @@ title: HotkeyCallback
type HotkeyCallback = (event, context) => void;
```
-Defined in: [hotkey.types.ts:233](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L233)
+Defined in: [hotkey.types.ts:250](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L250)
Callback function type for hotkey handlers.
diff --git a/docs/reference/type-aliases/HotkeyChord.md b/docs/reference/type-aliases/HotkeyChord.md
new file mode 100644
index 00000000..f7efaa76
--- /dev/null
+++ b/docs/reference/type-aliases/HotkeyChord.md
@@ -0,0 +1,67 @@
+---
+id: HotkeyChord
+title: HotkeyChord
+---
+
+```ts
+type HotkeyChord =
+ | Key
+ | SingleModifierHotkey
+ | TwoModifierHotkey
+ | ThreeModifierHotkey
+ | FourModifierHotkey;
+```
+
+Defined in: [hotkey.types.ts:126](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L126)
+
+A type-safe hotkey string.
+
+Provides autocomplete for:
+- All single keys (letters, numbers, function keys, navigation, editing, punctuation)
+- Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
+- Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
+- Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
+- Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)
+
+## Modifier Names
+
+Use canonical modifier names:
+- `Control` (not Ctrl) - The Control key
+- `Alt` (not Option) - The Alt key (Option on macOS)
+- `Meta` (not Command/Cmd) - The Meta/Command key (macOS only)
+- `Shift` - The Shift key
+
+## Platform-Adaptive `Mod` Modifier
+
+The `Mod` modifier is a special platform-adaptive modifier that automatically resolves
+to the "primary modifier" on each platform:
+
+- **macOS**: `Mod` → `Meta` (Command key ⌘)
+- **Windows/Linux**: `Mod` → `Control` (Ctrl key)
+
+This enables cross-platform hotkey definitions that work correctly on all platforms
+without platform-specific code. The `Mod` modifier is resolved at runtime based on
+the detected platform.
+
+**When to use `Mod` vs platform-specific modifiers:**
+- Use `Mod` for cross-platform shortcuts (e.g., `Mod+S` for save)
+- Use `Meta` or `Control` when you need platform-specific behavior
+- Use `Mod` when you want your shortcuts to follow platform conventions automatically
+
+**Limitations:**
+- `Mod+Control` and `Mod+Meta` combinations are not allowed (they create duplicate
+ modifiers on one platform)
+- In four-modifier combinations, only canonical modifiers are allowed (no `Mod`)
+
+## Example
+
+```ts
+// Cross-platform shortcuts (recommended)
+const save: HotkeyChord = 'Mod+S' // Command+S on Mac, Ctrl+S on Windows/Linux
+const saveAs: HotkeyChord = 'Mod+Shift+S' // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
+const comment: HotkeyChord = 'Mod+/' // Command+/ on Mac, Ctrl+/ elsewhere
+
+// Platform-specific shortcuts
+const macOnly: HotkeyChord = 'Meta+S' // Command+S on Mac only
+const windowsOnly: HotkeyChord = 'Control+S' // Ctrl+S on Windows/Linux only
+```
diff --git a/docs/reference/type-aliases/HotkeyConflict.md b/docs/reference/type-aliases/HotkeyConflict.md
deleted file mode 100644
index b8602ab2..00000000
--- a/docs/reference/type-aliases/HotkeyConflict.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-id: HotkeyConflict
-title: HotkeyConflict
----
-
-```ts
-type HotkeyConflict =
- | {
- registration: HotkeyRegistrationView;
- type: "hotkey";
-}
- | {
- registration: SequenceRegistrationView;
- type: "sequence";
-};
-```
-
-Defined in: [conflicts.ts:11](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/conflicts.ts#L11)
diff --git a/docs/reference/type-aliases/HotkeyOptionsFor.md b/docs/reference/type-aliases/HotkeyOptionsFor.md
new file mode 100644
index 00000000..e30c8b46
--- /dev/null
+++ b/docs/reference/type-aliases/HotkeyOptionsFor.md
@@ -0,0 +1,19 @@
+---
+id: HotkeyOptionsFor
+title: HotkeyOptionsFor
+---
+
+```ts
+type HotkeyOptionsFor = [T] extends [never] ? HotkeyChordOptions & HotkeySequenceOptions : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordOptions : T extends HotkeySequence ? HotkeySequenceOptions : HotkeyChordOptions;
+```
+
+Defined in: [hotkey-manager.ts:88](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L88)
+
+The options type for a hotkey: chord options for chords (including one-step
+tuples), sequence options for sequences.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`RegisterableHotkey`](RegisterableHotkey.md)
diff --git a/docs/reference/type-aliases/HotkeyRecorderCommitKeys.md b/docs/reference/type-aliases/HotkeyRecorderCommitKeys.md
new file mode 100644
index 00000000..065a616c
--- /dev/null
+++ b/docs/reference/type-aliases/HotkeyRecorderCommitKeys.md
@@ -0,0 +1,12 @@
+---
+id: HotkeyRecorderCommitKeys
+title: HotkeyRecorderCommitKeys
+---
+
+```ts
+type HotkeyRecorderCommitKeys = "enter" | "none";
+```
+
+Defined in: [hotkey-recorder.ts:34](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L34)
+
+Which keys commit a multi-step recording before it reaches `maxSteps`.
diff --git a/docs/reference/type-aliases/HotkeyRecorderOptions.md b/docs/reference/type-aliases/HotkeyRecorderOptions.md
new file mode 100644
index 00000000..7a0c8f19
--- /dev/null
+++ b/docs/reference/type-aliases/HotkeyRecorderOptions.md
@@ -0,0 +1,15 @@
+---
+id: HotkeyRecorderOptions
+title: HotkeyRecorderOptions
+---
+
+```ts
+type HotkeyRecorderOptions =
+ | HotkeyChordRecorderOptions
+ | HotkeySequenceRecorderOptions;
+```
+
+Defined in: [hotkey-recorder.ts:89](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-recorder.ts#L89)
+
+Options for HotkeyRecorder. `maxSteps` (default 1) selects between recording
+a single chord and recording a sequence.
diff --git a/docs/reference/type-aliases/HotkeyRegistration.md b/docs/reference/type-aliases/HotkeyRegistration.md
new file mode 100644
index 00000000..0e6e2398
--- /dev/null
+++ b/docs/reference/type-aliases/HotkeyRegistration.md
@@ -0,0 +1,14 @@
+---
+id: HotkeyRegistration
+title: HotkeyRegistration
+---
+
+```ts
+type HotkeyRegistration =
+ | HotkeyChordRegistration
+ | HotkeySequenceRegistration;
+```
+
+Defined in: [hotkey-manager.ts:132](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L132)
+
+A registered hotkey in the HotkeyManager.
diff --git a/docs/reference/type-aliases/HotkeyRegistrationView.md b/docs/reference/type-aliases/HotkeyRegistrationView.md
new file mode 100644
index 00000000..c0126f76
--- /dev/null
+++ b/docs/reference/type-aliases/HotkeyRegistrationView.md
@@ -0,0 +1,15 @@
+---
+id: HotkeyRegistrationView
+title: HotkeyRegistrationView
+---
+
+```ts
+type HotkeyRegistrationView =
+ | HotkeyChordRegistrationView
+ | HotkeySequenceRegistrationView;
+```
+
+Defined in: [hotkey-manager.ts:166](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L166)
+
+Public view of a hotkey registration for display and introspection.
+Narrow with `kind` to read chord- or sequence-specific fields.
diff --git a/docs/reference/type-aliases/HotkeySequence.md b/docs/reference/type-aliases/HotkeySequence.md
index 5ad23a84..faf50940 100644
--- a/docs/reference/type-aliases/HotkeySequence.md
+++ b/docs/reference/type-aliases/HotkeySequence.md
@@ -4,23 +4,14 @@ title: HotkeySequence
---
```ts
-type HotkeySequence = Hotkey[];
+type HotkeySequence = ReadonlyArray;
```
-Defined in: [sequence-manager.ts:52](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L52)
+Defined in: [hotkey.types.ts:211](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L211)
-A sequence of hotkeys for Vim-style shortcuts.
+A sequence of chords pressed one after another (Vim-style), such as `['G', 'G']`.
-Each element is one step (a `Hotkey` string). Steps may include modifiers;
-the same modifier can appear on consecutive steps (e.g. `Shift+R` then
-`Shift+T`). Modifier-only key events do not advance or reset matching—see
-`SequenceManager`. Automatic keydown repeats and IME composition are also ignored.
-
-## Example
-
-```ts
-const gotoTop: HotkeySequence = ['G', 'G'] // gg
-const deleteLine: HotkeySequence = ['D', 'D'] // dd
-const deleteWord: HotkeySequence = ['D', 'I', 'W'] // diw
-const chainedShift: HotkeySequence = ['Shift+R', 'Shift+T']
-```
+Steps may include modifiers; the same modifier can appear on consecutive
+steps (e.g. `['Shift+R', 'Shift+T']`). Modifier-only key events do not
+advance or reset matching. Automatic repeats and IME composition are ignored.
+A one-step sequence is treated as its single chord.
diff --git a/docs/reference/type-aliases/HotkeySequenceRecorderCommitKeys.md b/docs/reference/type-aliases/HotkeySequenceRecorderCommitKeys.md
deleted file mode 100644
index ce936ddf..00000000
--- a/docs/reference/type-aliases/HotkeySequenceRecorderCommitKeys.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-id: HotkeySequenceRecorderCommitKeys
-title: HotkeySequenceRecorderCommitKeys
----
-
-```ts
-type HotkeySequenceRecorderCommitKeys = "enter" | "none";
-```
-
-Defined in: [hotkey-sequence-recorder.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-sequence-recorder.ts#L25)
-
-How the user can commit a recorded sequence from the keyboard.
-- `'enter'`: plain Enter (no modifiers) commits when at least one step exists.
-- `'none'`: only [HotkeySequenceRecorder.commit](../classes/HotkeySequenceRecorder.md#commit) finishes recording (or idle timeout if set).
diff --git a/docs/reference/type-aliases/MultiHotkeyHandler.md b/docs/reference/type-aliases/MultiHotkeyHandler.md
index c3072b53..a421fe70 100644
--- a/docs/reference/type-aliases/MultiHotkeyHandler.md
+++ b/docs/reference/type-aliases/MultiHotkeyHandler.md
@@ -4,7 +4,7 @@ title: MultiHotkeyHandler
---
```ts
-type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
+type MultiHotkeyHandler = { [K in HotkeyChord]?: HotkeyCallback };
```
-Defined in: [match.ts:118](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L118)
+Defined in: [match.ts:126](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L126)
diff --git a/docs/reference/type-aliases/RegisterableHotkey.md b/docs/reference/type-aliases/RegisterableHotkey.md
index a7b9136f..59079525 100644
--- a/docs/reference/type-aliases/RegisterableHotkey.md
+++ b/docs/reference/type-aliases/RegisterableHotkey.md
@@ -4,10 +4,11 @@ title: RegisterableHotkey
---
```ts
-type RegisterableHotkey = Hotkey | RawHotkey;
+type RegisterableHotkey =
+ | RegisterableHotkeyChord
+ | HotkeySequence;
```
-Defined in: [hotkey.types.ts:207](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L207)
+Defined in: [hotkey.types.ts:224](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L224)
-A hotkey that can be passed to `HotkeyManager.register()` and `useHotkey()`.
-Either a type-safe string (`Hotkey`) or a raw object (`RawHotkey`).
+Anything that can be registered: a chord string, a raw chord object, or a sequence.
diff --git a/docs/reference/type-aliases/RegisterableHotkeyChord.md b/docs/reference/type-aliases/RegisterableHotkeyChord.md
new file mode 100644
index 00000000..a7eb805c
--- /dev/null
+++ b/docs/reference/type-aliases/RegisterableHotkeyChord.md
@@ -0,0 +1,12 @@
+---
+id: RegisterableHotkeyChord
+title: RegisterableHotkeyChord
+---
+
+```ts
+type RegisterableHotkeyChord = HotkeyChord | RawHotkey;
+```
+
+Defined in: [hotkey.types.ts:219](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.types.ts#L219)
+
+A single chord as a type-safe string (`HotkeyChord`) or a raw object (`RawHotkey`).
diff --git a/docs/reference/type-aliases/RegisteredAppHotkeys.md b/docs/reference/type-aliases/RegisteredAppHotkeys.md
new file mode 100644
index 00000000..5ab61005
--- /dev/null
+++ b/docs/reference/type-aliases/RegisteredAppHotkeys.md
@@ -0,0 +1,12 @@
+---
+id: RegisteredAppHotkeys
+title: RegisteredAppHotkeys
+---
+
+```ts
+type RegisteredAppHotkeys = Register extends object ? T : AppHotkeys;
+```
+
+Defined in: [app-hotkeys.ts:144](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/app-hotkeys.ts#L144)
+
+The app hotkeys type from `Register`, or a generic map when none is registered.
diff --git a/docs/reference/type-aliases/Target.md b/docs/reference/type-aliases/Target.md
index 6bd059fe..ca4039b3 100644
--- a/docs/reference/type-aliases/Target.md
+++ b/docs/reference/type-aliases/Target.md
@@ -7,4 +7,6 @@ title: Target
type Target = HTMLElement | Document | Window;
```
-Defined in: [sequence-manager.ts:25](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L25)
+Defined in: [hotkey-manager.ts:40](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey-manager.ts#L40)
+
+An element, document, or window that hotkeys can listen on.
diff --git a/docs/reference/type-aliases/ValidatableHotkey.md b/docs/reference/type-aliases/ValidatableHotkey.md
new file mode 100644
index 00000000..64af1e4f
--- /dev/null
+++ b/docs/reference/type-aliases/ValidatableHotkey.md
@@ -0,0 +1,12 @@
+---
+id: ValidatableHotkey
+title: ValidatableHotkey
+---
+
+```ts
+type ValidatableHotkey = Hotkey | string & object | ReadonlyArray;
+```
+
+Defined in: [validate.ts:6](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/validate.ts#L6)
+
+A hotkey to validate: a chord string, a sequence, or untyped input such as saved data.
diff --git a/docs/reference/variables/DEFAULT_SEQUENCE_TIMEOUT.md b/docs/reference/variables/DEFAULT_SEQUENCE_TIMEOUT.md
index 14a84d70..5709b1b9 100644
--- a/docs/reference/variables/DEFAULT_SEQUENCE_TIMEOUT.md
+++ b/docs/reference/variables/DEFAULT_SEQUENCE_TIMEOUT.md
@@ -7,7 +7,6 @@ title: DEFAULT_SEQUENCE_TIMEOUT
const DEFAULT_SEQUENCE_TIMEOUT: 1000 = 1000;
```
-Defined in: [sequence-manager.ts:58](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/sequence-manager.ts#L58)
+Defined in: [match.ts:235](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L235)
-Default timeout between keys in a sequence (in milliseconds).
-Exported for consumers that display sequence state (e.g. devtools).
+Default timeout between sequence steps (in milliseconds).
diff --git a/examples/alpine/createHotkeySequence/index.html b/examples/alpine/createHotkey-sequences/index.html
similarity index 96%
rename from examples/alpine/createHotkeySequence/index.html
rename to examples/alpine/createHotkey-sequences/index.html
index f1d17032..3f3b9411 100644
--- a/examples/alpine/createHotkeySequence/index.html
+++ b/examples/alpine/createHotkey-sequences/index.html
@@ -3,15 +3,16 @@
- TanStack Hotkeys | Alpine createHotkeySequence
+ TanStack Hotkeys | Alpine Sequences with createHotkey
-
scope.createHotkeySequence
+
Sequences with scope.createHotkey
- Register multi-key sequences (like Vim commands). Keys must be
+ Pass an array of chords to scope.createHotkey to
+ register a multi-key sequence (like Vim commands). Keys must be
pressed within the timeout window (default: 1000ms).
- Customize Vim-style sequences. Click Edit, press each chord in
- order, then press Enter to save. Escape cancels; Backspace removes
- the last chord or clears when empty.
+ scope.createHotkeyRecorder with
+ maxSteps records up to that many chords. Click Edit,
+ press each chord in order, then press Enter (or reach four chords)
+ to save. One chord saves as a regular hotkey. Escape cancels;
+ Backspace removes the last chord or clears when empty.
@@ -70,7 +72,7 @@
Shortcuts
@@ -101,16 +103,12 @@
Shortcuts
-
+
-
+
No shortcut
@@ -171,21 +169,13 @@
Shortcuts
- Recording sequence...
- Press each chord, then Enter to finish. Escape cancels. Backspace
- removes the last chord or clears.
+ Recording...
+ Press up to four chords, then Enter to finish. Escape cancels.
+ Backspace removes the last chord or clears.
-
-
-
-
-
-
+
@@ -201,34 +191,33 @@
Live Registrations
This table is powered by
scope.createHotkeyRegistrations()
— trigger counts, names, and descriptions update in real-time as
- you use your sequences.
+ you use your shortcuts.
- Register many multi-key sequences in one hook (like Vim commands).
- Keys must be pressed within the timeout window (default: 1000ms).
+ Register many multi-key sequences in one
+ scope.createHotkeys call by passing arrays of chords
+ (like Vim commands). Keys must be pressed within the timeout window
+ (default: 1000ms).
@@ -203,70 +205,34 @@
Live Registrations (scope.createHotkeyRegistrations)
This table is rendered from
scope.createHotkeyRegistrations()
— a reactive view of all registered hotkeys and sequences.
- Trigger counts update in real-time.
+ Progress and trigger counts update in real-time.
-
-
-
Live Registrations (scope.createHotkeyRegistrations)
This table is rendered from
scope.createHotkeyRegistrations()
- — a reactive view of all registered hotkeys. It updates
- automatically as hotkeys are added, removed, enabled/disabled, or
- triggered.
+ — a reactive view of all registered hotkeys, chords and sequences.
+ It updates automatically as hotkeys are added, removed,
+ enabled/disabled, or triggered.
@@ -157,6 +157,7 @@
Live Registrations (scope.createHotkeyRegistrations)
Hotkey
Name
Description
+
Progress
Enabled
Triggers
@@ -172,6 +173,9 @@
Live Registrations (scope.createHotkeyRegistrations)