+ )
+}
+```
+
+## Platform Symbols Reference
+
+On macOS, modifiers are displayed as symbols:
+
+| Modifier | Mac Symbol | Windows/Linux Label |
+|----------|-----------|-------------------|
+| Meta (Cmd) | `⌘` | `Win` / `Super` |
+| Control | `⌃` | `Ctrl` |
+| Alt/Option | `⌥` | `Alt` |
+| Shift | `⇧` | `Shift` |
+
+Special keys also have display symbols:
+
+| Key | Display |
+|-----|---------|
+| Escape | `Esc` |
+| Backspace | `⌫` (Mac) / `Backspace` |
+| Delete | `⌦` (Mac) / `Del` |
+| Enter | `↵` |
+| Tab | `⇥` |
+| ArrowUp | `↑` |
+| ArrowDown | `↓` |
+| ArrowLeft | `←` |
+| ArrowRight | `→` |
+| Space | `Space` |
+
+## Parsing and Normalization
+
+TanStack Hotkeys also provides utilities for parsing and normalizing hotkey strings:
+
+### `parseHotkey`
+
+Parse a hotkey string into its component parts:
+
+```ts
+import { parseHotkey } from '@tanstack/preact-hotkeys'
+
+const parsed = parseHotkey('Mod+Shift+S')
+// {
+// key: 'S',
+// ctrl: false, // true on Windows/Linux
+// shift: true,
+// alt: false,
+// meta: true, // true on Mac
+// modifiers: ['Shift', 'Meta'] // or ['Control', 'Shift'] on Windows
+// }
+```
+
+### `normalizeHotkey`
+
+Normalize a hotkey string to its canonical form:
+
+```ts
+import { normalizeHotkey } from '@tanstack/preact-hotkeys'
+
+normalizeHotkey('Cmd+S') // 'Meta+S' (on Mac)
+normalizeHotkey('Ctrl+Shift+s') // 'Control+Shift+S'
+normalizeHotkey('Mod+S') // 'Meta+S' (on Mac) or 'Control+S' (on Windows)
+```
+
+## Validation
+
+Use `validateHotkey` to check if a hotkey string is valid and get warnings about potential platform issues:
+
+```ts
+import { validateHotkey } from '@tanstack/preact-hotkeys'
+
+const result = validateHotkey('Alt+A')
+// {
+// valid: true,
+// warnings: ['Alt+letter combinations may not work on macOS due to special characters'],
+// errors: []
+// }
+
+const result2 = validateHotkey('InvalidKey+S')
+// {
+// valid: false,
+// warnings: [],
+// errors: ['Unknown key: InvalidKey']
+// }
+```
diff --git a/docs/framework/preact/guides/hotkey-recording.md b/docs/framework/preact/guides/hotkey-recording.md
new file mode 100644
index 0000000..75c54ec
--- /dev/null
+++ b/docs/framework/preact/guides/hotkey-recording.md
@@ -0,0 +1,168 @@
+---
+title: Hotkey Recording Guide
+id: hotkey-recording
+---
+
+TanStack Hotkeys provides the `useHotkeyRecorder` hook for building keyboard shortcut customization UIs. This lets users record their own shortcuts by pressing the desired key combination, similar to how system preferences or IDE shortcut editors work.
+
+## Basic Usage
+
+```tsx
+import { useHotkeyRecorder, formatForDisplay } from '@tanstack/preact-hotkeys'
+
+function ShortcutRecorder() {
+ const { isRecording, recordedHotkey, startRecording, stopRecording, cancelRecording } =
+ useHotkeyRecorder({
+ onRecord: (hotkey) => {
+ console.log('Recorded:', hotkey) // e.g., "Mod+Shift+S"
+ },
+ })
+
+ return (
+
+
+ {isRecording && (
+
+ )}
+
+ )
+}
+```
+
+## Return Value
+
+The `useHotkeyRecorder` hook returns an object with:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isRecording` | `boolean` | Whether the recorder is currently listening for key presses |
+| `recordedHotkey` | `Hotkey \| null` | The last recorded hotkey string, or `null` if nothing recorded |
+| `startRecording` | `() => void` | Start listening for key presses |
+| `stopRecording` | `() => void` | Stop listening and keep the recorded hotkey |
+| `cancelRecording` | `() => void` | Stop listening and discard any recorded hotkey |
+
+## Options
+
+```tsx
+useHotkeyRecorder({
+ onRecord: (hotkey) => { /* called when a hotkey is recorded */ },
+ onCancel: () => { /* called when recording is cancelled */ },
+ onClear: () => { /* called when the recorded hotkey is cleared */ },
+})
+```
+
+### `onRecord`
+
+Called when the user presses a valid key combination (a modifier + a non-modifier key, or a single non-modifier key). Receives the recorded `Hotkey` string.
+
+### `onCancel`
+
+Called when recording is cancelled (either by pressing Escape or calling `cancelRecording()`).
+
+### `onClear`
+
+Called when the recorded hotkey is cleared (by pressing Backspace or Delete during recording).
+
+### Global Default Options via Provider
+
+You can set default options for all `useHotkeyRecorder` calls by wrapping your component tree with `HotkeysProvider`. Per-hook options will override the provider defaults.
+
+```tsx
+import { HotkeysProvider } from '@tanstack/preact-hotkeys'
+
+ console.log('Recording cancelled'),
+ },
+ }}
+>
+
+
+```
+
+## Recording Behavior
+
+The recorder has specific behavior for different keys:
+
+| Key | Behavior |
+|-----|----------|
+| **Modifier only** (Shift, Ctrl, etc.) | Waits for a non-modifier key -- modifier-only presses don't complete a recording |
+| **Modifier + key** (e.g., Ctrl+S) | Records the full combination |
+| **Single key** (e.g., Escape, F1) | Records the single key |
+| **Escape** | Cancels the recording |
+| **Backspace / Delete** | Clears the currently recorded hotkey |
+
+### Mod Auto-Conversion
+
+Recorded hotkeys automatically use the portable `Mod` format. If a user on macOS presses Command+S, the recorded hotkey will be `Mod+S` rather than `Meta+S`. This ensures shortcuts are portable across platforms.
+
+## Building a Shortcut Settings UI
+
+Here's a more complete example of a shortcut customization panel:
+
+```tsx
+import { useState } from 'preact/hooks'
+import {
+ useHotkey,
+ useHotkeyRecorder,
+ formatForDisplay,
+} from '@tanstack/preact-hotkeys'
+import type { Hotkey } from '@tanstack/preact-hotkeys'
+
+function ShortcutSettings() {
+ const [shortcuts, setShortcuts] = useState>({
+ save: 'Mod+S',
+ undo: 'Mod+Z',
+ search: 'Mod+K',
+ })
+
+ const [editingAction, setEditingAction] = useState(null)
+
+ const recorder = useHotkeyRecorder({
+ onRecord: (hotkey) => {
+ if (editingAction) {
+ setShortcuts((prev) => ({ ...prev, [editingAction]: hotkey }))
+ setEditingAction(null)
+ }
+ },
+ onCancel: () => setEditingAction(null),
+ })
+
+ // Register the actual hotkeys with their current bindings
+ useHotkey(shortcuts.save, () => save())
+ useHotkey(shortcuts.undo, () => undo())
+ useHotkey(shortcuts.search, () => openSearch())
+
+ return (
+
+ )
+}
+```
+
+## Under the Hood
+
+The `useHotkeyRecorder` hook creates a `HotkeyRecorder` class instance and subscribes to its reactive state via `@tanstack/preact-store`. The class manages its own keyboard event listeners and state, and the hook handles cleanup on unmount.
diff --git a/docs/framework/preact/guides/hotkeys.md b/docs/framework/preact/guides/hotkeys.md
new file mode 100644
index 0000000..ad7aa8a
--- /dev/null
+++ b/docs/framework/preact/guides/hotkeys.md
@@ -0,0 +1,252 @@
+---
+title: Hotkeys Guide
+id: hotkeys
+---
+
+The `useHotkey` hook is the primary way to register keyboard shortcuts in Preact applications. It wraps the singleton `HotkeyManager` with automatic lifecycle management, stale-closure prevention, and Preact ref support.
+
+## Basic Usage
+
+```tsx
+import { useHotkey } from '@tanstack/preact-hotkeys'
+
+function App() {
+ useHotkey('Mod+S', () => {
+ saveDocument()
+ }, {
+ // override the default options here
+ })
+}
+```
+
+The callback receives the original `KeyboardEvent` as the first argument and a `HotkeyCallbackContext` as the second:
+
+```tsx
+useHotkey('Mod+S', (event, context) => {
+ console.log(context.hotkey) // 'Mod+S'
+ console.log(context.parsedHotkey) // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+})
+```
+
+You can pass a hotkey as a string or as a `RawHotkey` object (modifier booleans optional). Use `mod` for cross-platform shortcuts (Command on Mac, Control elsewhere):
+
+```tsx
+useHotkey('Mod+S', () => save())
+useHotkey({ key: 'S', mod: true }, () => save()) // Same as above
+useHotkey({ key: 'Escape' }, () => closeModal())
+useHotkey({ key: 'S', ctrl: true, shift: true }, () => saveAs())
+useHotkey({ key: 'S', mod: true, shift: true }, () => saveAs())
+```
+
+## Default Options
+
+When you register a hotkey without passing options, or when you omit specific options, the following defaults apply:
+
+```tsx
+useHotkey('Mod+S', callback, {
+ enabled: true,
+ preventDefault: true,
+ stopPropagation: true,
+ eventType: 'keydown',
+ requireReset: false,
+ ignoreInputs: undefined, // smart default: false for Mod+S, true for single keys
+ target: document,
+ platform: undefined, // auto-detected
+ conflictBehavior: 'warn',
+})
+```
+
+### Why These Defaults?
+
+Most hotkey registrations are intended to override default browser behavior—such as using `Mod+S` to save a document instead of showing the browser's "Save Page" dialog. To make this easy and consistent, the library sets `preventDefault` and `stopPropagation` to `true` by default, ensuring your hotkey handlers take precedence and reducing the amount of repetitive boilerplate code required.
+
+#### Smart Input Handling: `ignoreInputs`
+
+The `ignoreInputs` option is designed to strike a balance between accessibility and usability. By default, hotkeys involving `Ctrl`/`Meta` modifiers (like `Mod+S`) and the `Escape` key are allowed to fire even when the focus is inside input elements (such as text fields or text areas), and when focused on button-type inputs (`type="button"`, `"submit"`, or `"reset"`). This allows shortcuts like save or close to work wherever the user is focused. On the other hand, single key shortcuts or those using only `Shift`/`Alt` are ignored within non-button inputs to prevent interference with normal typing.
+
+#### Hotkey Conflicts: `conflictBehavior`
+
+When you attempt to register a hotkey that is already registered (possibly in another part of your app), the library logs a warning by default using the `conflictBehavior: 'warn'` setting. This helps you catch accidental duplicate bindings during development so they can be resolved before reaching production.
+
+
+### Global Default Options via Provider
+
+You can change the default options for all `useHotkey` calls in your app by wrapping your component tree with `HotkeysProvider`. Per-hook options will override the provider defaults.
+
+```tsx
+import { HotkeysProvider } from '@tanstack/preact-hotkeys'
+
+
+
+
+```
+
+## Hotkey Options
+
+### `enabled`
+
+Controls whether the hotkey is active. Defaults to `true`.
+
+```tsx
+const [isEditing, setIsEditing] = useState(false)
+
+// Only active when editing
+useHotkey('Mod+S', () => save(), { enabled: isEditing })
+```
+
+### `preventDefault`
+
+Automatically calls `event.preventDefault()` when the hotkey fires. Defaults to `true`.
+
+```tsx
+// Browser default is prevented by default
+useHotkey('Mod+S', () => save())
+
+// Opt out when you want the browser's default behavior
+useHotkey('Mod+S', () => save(), { preventDefault: false })
+```
+
+### `stopPropagation`
+
+Calls `event.stopPropagation()` when the hotkey fires. Defaults to `true`.
+
+```tsx
+// Event propagation is stopped by default
+useHotkey('Escape', () => closeModal())
+
+// Opt out when you need the event to bubble
+useHotkey('Escape', () => closeModal(), { stopPropagation: false })
+```
+
+### `eventType`
+
+Whether to listen on `keydown` (default) or `keyup`.
+
+```tsx
+// Fire when the key is released
+useHotkey('Shift', () => deactivateMode(), { eventType: 'keyup' })
+```
+
+### `requireReset`
+
+When `true`, the hotkey will only fire once per key press. The key must be released and pressed again to fire again. Defaults to `false`.
+
+```tsx
+// Only fires once per Escape press, not on key repeat
+useHotkey('Escape', () => closePanel(), { requireReset: true })
+```
+
+### `ignoreInputs`
+
+When `true`, the hotkey will not fire when the user is focused on a text input, textarea, select, or contentEditable element. Button-type inputs (`type="button"`, `"submit"`, `"reset"`) are not ignored, so shortcuts like Mod+S work when the user has tabbed to a form button. When unset, a smart default applies: `Ctrl`/`Meta` shortcuts and `Escape` fire in inputs; single keys and `Shift`/`Alt` combos are ignored.
+
+```tsx
+// Single key - ignored in inputs by default (smart default)
+useHotkey('K', () => openSearch())
+
+// Mod+S and Escape - fire in inputs by default (smart default)
+useHotkey('Mod+S', () => save())
+useHotkey('Escape', () => closeDialog())
+
+// Override: force a single key to fire in inputs
+useHotkey('Enter', () => submit(), { ignoreInputs: false })
+```
+
+Set `ignoreInputs: false` or `true` explicitly to override the smart default.
+
+### `target`
+
+The DOM element to attach the event listener to. Defaults to `document`. Can be a DOM element, `document`, `window`, or a Preact ref.
+
+```tsx
+import { useRef } from 'preact/hooks'
+
+function Panel() {
+ const panelRef = useRef(null)
+
+ // Only listens for events on this specific element
+ useHotkey('Escape', () => closePanel(), { target: panelRef })
+
+ return (
+
+
Panel content
+
+ )
+}
+```
+
+> [!NOTE]
+> When using a ref as the target, make sure the element is focusable (has `tabIndex`) so it can receive keyboard events.
+
+### `conflictBehavior`
+
+Controls what happens when you register a hotkey that's already registered. Options:
+
+- `'warn'` (default) - Logs a warning but allows the registration
+- `'error'` - Throws an error
+- `'replace'` - Replaces the existing registration
+- `'allow'` - Allows multiple registrations silently
+
+```tsx
+useHotkey('Mod+S', () => save(), { conflictBehavior: 'replace' })
+```
+
+### `platform`
+
+Override the auto-detected platform. Useful for testing or for applications that need to force a specific platform behavior.
+
+```tsx
+useHotkey('Mod+S', () => save(), { platform: 'mac' })
+```
+
+## Stale Closure Prevention
+
+The `useHotkey` hook automatically syncs the callback on every render, so you never need to worry about stale closures:
+
+```tsx
+function Counter() {
+ const [count, setCount] = useState(0)
+
+ // This callback always has access to the latest `count` value
+ useHotkey('Mod+Shift+C', () => {
+ console.log('Current count:', count)
+ })
+
+ return
+}
+```
+
+## Automatic Cleanup
+
+The hook automatically unregisters the hotkey when the component unmounts:
+
+```tsx
+function TemporaryPanel() {
+ // Automatically cleaned up when this component unmounts
+ useHotkey('Escape', () => closePanel())
+
+ return
Panel content
+}
+```
+
+## The Hotkey Manager
+
+Under the hood, `useHotkey` uses the singleton `HotkeyManager`. You can also access the manager directly if needed:
+
+```tsx
+import { getHotkeyManager } from '@tanstack/preact-hotkeys'
+
+const manager = getHotkeyManager()
+
+// Check if a hotkey is registered
+manager.isRegistered('Mod+S')
+
+// Get total number of registrations
+manager.getRegistrationCount()
+```
+
+The manager attaches event listeners per target element, so only elements that have registered hotkeys receive listeners. This is more efficient than a single global listener.
diff --git a/docs/framework/preact/guides/key-state-tracking.md b/docs/framework/preact/guides/key-state-tracking.md
new file mode 100644
index 0000000..ca082ce
--- /dev/null
+++ b/docs/framework/preact/guides/key-state-tracking.md
@@ -0,0 +1,186 @@
+---
+title: Key State Tracking Guide
+id: key-state-tracking
+---
+
+TanStack Hotkeys provides three hooks for tracking the real-time state of keyboard keys. These are useful for building UIs that respond to modifier keys being held, displaying active key states, or implementing hold-to-activate features.
+
+## `useHeldKeys`
+
+Returns a reactive array of all currently held key names.
+
+```tsx
+import { useHeldKeys } from '@tanstack/preact-hotkeys'
+
+function KeyDisplay() {
+ const heldKeys = useHeldKeys()
+
+ return (
+
+ )
+}
+```
+
+The returned array contains key names like `'Shift'`, `'Control'`, `'Meta'`, `'A'`, `'ArrowUp'`, etc. Keys appear in the order they were pressed.
+
+## `useHeldKeyCodes`
+
+Returns a reactive object mapping held key names to their physical key codes (`event.code` values). This is useful when you need to distinguish between left and right modifiers.
+
+```tsx
+import { useHeldKeyCodes } from '@tanstack/preact-hotkeys'
+
+function KeyCodeDisplay() {
+ const heldCodes = useHeldKeyCodes()
+ // Example: { Shift: "ShiftLeft", Control: "ControlRight" }
+
+ return (
+
+ )
+}
+```
+
+## `useKeyHold`
+
+Checks whether a specific key is currently held. This hook is optimized to only trigger re-renders when the specified key's held state changes, not when other keys are pressed or released.
+
+```tsx
+import { useKeyHold } from '@tanstack/preact-hotkeys'
+
+function ModifierIndicators() {
+ const isShiftHeld = useKeyHold('Shift')
+ const isCtrlHeld = useKeyHold('Control')
+ const isAltHeld = useKeyHold('Alt')
+ const isMetaHeld = useKeyHold('Meta')
+
+ return (
+
+ Shift
+ Ctrl
+ Alt
+ Meta
+
+ )
+}
+```
+
+## Common Patterns
+
+### Hold-to-Reveal UI
+
+Show additional options while a modifier is held:
+
+```tsx
+import { useKeyHold } from '@tanstack/preact-hotkeys'
+
+function FileItem({ file }: { file: File }) {
+ const isShiftHeld = useKeyHold('Shift')
+
+ return (
+
+ )
+}
+```
+
+## Platform Quirks
+
+The underlying `KeyStateTracker` handles several platform-specific issues:
+
+### macOS Modifier Key Behavior
+
+On macOS, when a modifier key is held and a non-modifier key is pressed, the OS sometimes swallows the `keyup` event for the non-modifier key. TanStack Hotkeys detects and handles this automatically so held key state stays accurate.
+
+### Window Blur
+
+When the browser window loses focus, all held keys are automatically cleared. This prevents "stuck" keys that would otherwise appear held even after the user tabs away and releases them.
+
+## Under the Hood
+
+All three hooks subscribe to the singleton `KeyStateTracker` via `@tanstack/preact-store`. The tracker manages its own event listeners on `document` and maintains state in a TanStack Store, which the hooks subscribe to reactively.
+
+```tsx
+import { getKeyStateTracker } from '@tanstack/preact-hotkeys'
+
+const tracker = getKeyStateTracker()
+
+// Imperative access (outside of Preact)
+tracker.getHeldKeys() // string[]
+tracker.isKeyHeld('Shift') // boolean
+tracker.isAnyKeyHeld(['Shift', 'Control']) // boolean
+tracker.areAllKeysHeld(['Shift', 'Control']) // boolean
+```
diff --git a/docs/framework/preact/guides/sequences.md b/docs/framework/preact/guides/sequences.md
new file mode 100644
index 0000000..a06a08c
--- /dev/null
+++ b/docs/framework/preact/guides/sequences.md
@@ -0,0 +1,171 @@
+---
+title: Sequences Guide
+id: sequences
+---
+
+TanStack Hotkeys supports multi-key sequences -- shortcuts where you press keys one after another rather than simultaneously. This is commonly used for Vim-style navigation, cheat codes, or multi-step commands.
+
+## Basic Usage
+
+Use the `useHotkeySequence` hook to register a key sequence:
+
+```tsx
+import { useHotkeySequence } from '@tanstack/preact-hotkeys'
+
+function App() {
+ // Vim-style: press g then g to scroll to top
+ useHotkeySequence(['G', 'G'], () => {
+ window.scrollTo({ top: 0, behavior: 'smooth' })
+ })
+}
+```
+
+The first argument is an array of `Hotkey` strings representing each step in the sequence. The user must press them in order within the timeout window.
+
+## Sequence Options
+
+The third argument is an options object:
+
+```tsx
+useHotkeySequence(['G', 'G'], callback, {
+ timeout: 1000, // Time allowed between keys (ms)
+ enabled: true, // Whether the sequence is active
+ target: document, // Or a Preact ref for scoped sequences
+})
+```
+
+### `timeout`
+
+The maximum time (in milliseconds) allowed between consecutive key presses. If the user takes longer than this between any two keys, the sequence resets. Defaults to `1000` (1 second).
+
+```tsx
+// Fast sequence - user must type quickly
+useHotkeySequence(['D', 'D'], () => deleteLine(), { timeout: 500 })
+
+// Slow sequence - user has more time between keys
+useHotkeySequence(['Shift+Z', 'Shift+Z'], () => forceQuit(), { timeout: 2000 })
+```
+
+### `enabled`
+
+Controls whether the sequence is active. Defaults to `true`.
+
+```tsx
+const [isVimMode, setIsVimMode] = useState(true)
+
+useHotkeySequence(['G', 'G'], () => scrollToTop(), { enabled: isVimMode })
+```
+
+### `target`
+
+The DOM element to attach the sequence listener to. Defaults to `document`. Can be a Preact ref, DOM element, `document`, or `window` for scoped sequences.
+
+### Global Default Options via Provider
+
+You can set default options for all `useHotkeySequence` calls by wrapping your component tree with `HotkeysProvider`. Per-hook options will override the provider defaults.
+
+```tsx
+import { HotkeysProvider } from '@tanstack/preact-hotkeys'
+
+
+
+
+```
+
+## Sequences with Modifiers
+
+Each step in a sequence can include modifiers:
+
+```tsx
+// Ctrl+K followed by Ctrl+C (VS Code-style comment)
+useHotkeySequence(['Mod+K', 'Mod+C'], () => {
+ commentSelection()
+})
+
+// g then Shift+G (go to bottom, Vim-style)
+useHotkeySequence(['G', 'Shift+G'], () => {
+ scrollToBottom()
+})
+```
+
+## Common Sequence Patterns
+
+### Vim-Style Navigation
+
+```tsx
+function VimNavigation() {
+ useHotkeySequence(['G', 'G'], () => scrollToTop())
+ useHotkeySequence(['G', 'Shift+G'], () => scrollToBottom())
+ useHotkeySequence(['D', 'D'], () => deleteLine())
+ useHotkeySequence(['D', 'W'], () => deleteWord())
+ useHotkeySequence(['C', 'I', 'W'], () => changeInnerWord())
+}
+```
+
+### Konami Code
+
+```tsx
+useHotkeySequence(
+ [
+ 'ArrowUp', 'ArrowUp',
+ 'ArrowDown', 'ArrowDown',
+ 'ArrowLeft', 'ArrowRight',
+ 'ArrowLeft', 'ArrowRight',
+ 'B', 'A',
+ ],
+ () => enableEasterEgg(),
+ { timeout: 2000 },
+)
+```
+
+### Multi-Step Commands
+
+```tsx
+// Press "h", "e", "l", "p" to open help
+useHotkeySequence(['H', 'E', 'L', 'P'], () => openHelp())
+```
+
+## How Sequences Work
+
+The `SequenceManager` (singleton) handles all sequence registrations. When a key is pressed:
+
+1. It checks if the key matches the next expected step in any registered sequence
+2. If it matches, the sequence advances to the next step
+3. If the timeout expires between steps, the sequence resets
+4. When all steps are completed, the callback fires
+
+### Overlapping Sequences
+
+Multiple sequences can share the same prefix. The manager tracks progress for each sequence independently:
+
+```tsx
+// Both share the 'D' prefix
+useHotkeySequence(['D', 'D'], () => deleteLine()) // dd
+useHotkeySequence(['D', 'W'], () => deleteWord()) // dw
+useHotkeySequence(['D', 'I', 'W'], () => deleteInnerWord()) // diw
+```
+
+After pressing `D`, the manager waits for the next key to determine which sequence to complete.
+
+## The Sequence Manager
+
+Under the hood, `useHotkeySequence` uses the singleton `SequenceManager`. You can also use the core `createSequenceMatcher` function for standalone sequence matching without the singleton:
+
+```tsx
+import { createSequenceMatcher } from '@tanstack/preact-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/2
+})
+```
diff --git a/docs/framework/preact/reference/functions/HotkeysProvider.md b/docs/framework/preact/reference/functions/HotkeysProvider.md
new file mode 100644
index 0000000..ceb8849
--- /dev/null
+++ b/docs/framework/preact/reference/functions/HotkeysProvider.md
@@ -0,0 +1,22 @@
+---
+id: HotkeysProvider
+title: HotkeysProvider
+---
+
+# Function: HotkeysProvider()
+
+```ts
+function HotkeysProvider(__namedParameters): Element;
+```
+
+Defined in: [HotkeysProvider.tsx:27](https://github.com/TanStack/hotkeys/blob/main/packages/preact-hotkeys/src/HotkeysProvider.tsx#L27)
+
+## Parameters
+
+### \_\_namedParameters
+
+[`HotkeysProviderProps`](../interfaces/HotkeysProviderProps.md)
+
+## Returns
+
+`Element`
diff --git a/docs/framework/preact/reference/functions/useDefaultHotkeysOptions.md b/docs/framework/preact/reference/functions/useDefaultHotkeysOptions.md
new file mode 100644
index 0000000..9cc15af
--- /dev/null
+++ b/docs/framework/preact/reference/functions/useDefaultHotkeysOptions.md
@@ -0,0 +1,16 @@
+---
+id: useDefaultHotkeysOptions
+title: useDefaultHotkeysOptions
+---
+
+# Function: useDefaultHotkeysOptions()
+
+```ts
+function useDefaultHotkeysOptions(): HotkeysProviderOptions;
+```
+
+Defined in: [HotkeysProvider.tsx:49](https://github.com/TanStack/hotkeys/blob/main/packages/preact-hotkeys/src/HotkeysProvider.tsx#L49)
+
+## Returns
+
+[`HotkeysProviderOptions`](../interfaces/HotkeysProviderOptions.md)
diff --git a/docs/framework/preact/reference/functions/useHeldKeyCodes.md b/docs/framework/preact/reference/functions/useHeldKeyCodes.md
new file mode 100644
index 0000000..586b59c
--- /dev/null
+++ b/docs/framework/preact/reference/functions/useHeldKeyCodes.md
@@ -0,0 +1,42 @@
+---
+id: useHeldKeyCodes
+title: useHeldKeyCodes
+---
+
+# Function: useHeldKeyCodes()
+
+```ts
+function useHeldKeyCodes(): Record;
+```
+
+Defined in: [useHeldKeyCodes.ts:30](https://github.com/TanStack/hotkeys/blob/main/packages/preact-hotkeys/src/useHeldKeyCodes.ts#L30)
+
+Preact hook that returns a map of currently held key names to their physical `event.code` values.
+
+This is useful for debugging which physical key was pressed (e.g. distinguishing
+left vs right Shift via "ShiftLeft" / "ShiftRight").
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+Record mapping normalized key names to their `event.code` values
+
+## Example
+
+```tsx
+function KeyDebugDisplay() {
+ const heldKeys = useHeldKeys()
+ const heldCodes = useHeldKeyCodes()
+
+ return (
+
+ )
+}
+```
+
+## Platform Symbols Reference
+
+| Modifier | Mac Symbol | Windows/Linux Label |
+|----------|-----------|-------------------|
+| Meta (Cmd) | `⌘` | `Win` / `Super` |
+| Control | `⌃` | `Ctrl` |
+| Alt/Option | `⌥` | `Alt` |
+| Shift | `⇧` | `Shift` |
+
+## Parsing and Normalization
+
+### `parseHotkey`
+
+```ts
+import { parseHotkey } from '@tanstack/solid-hotkeys'
+
+const parsed = parseHotkey('Mod+Shift+S')
+// { key: 'S', ctrl: false, shift: true, alt: false, meta: true, modifiers: [...] }
+```
+
+### `normalizeHotkey`
+
+```ts
+import { normalizeHotkey } from '@tanstack/solid-hotkeys'
+
+normalizeHotkey('Cmd+S') // 'Meta+S' (on Mac)
+normalizeHotkey('Ctrl+Shift+s') // 'Control+Shift+S'
+```
+
+## Validation
+
+```ts
+import { validateHotkey } from '@tanstack/solid-hotkeys'
+
+const result = validateHotkey('Alt+A')
+// { valid: true, warnings: [...], errors: [] }
+
+const result2 = validateHotkey('InvalidKey+S')
+// { valid: false, warnings: [], errors: ['Unknown key: InvalidKey'] }
+```
diff --git a/docs/framework/solid/guides/hotkey-recording.md b/docs/framework/solid/guides/hotkey-recording.md
new file mode 100644
index 0000000..91b5c3c
--- /dev/null
+++ b/docs/framework/solid/guides/hotkey-recording.md
@@ -0,0 +1,169 @@
+---
+title: Hotkey Recording Guide
+id: hotkey-recording
+---
+
+TanStack Hotkeys provides the `createHotkeyRecorder` primitive for building keyboard shortcut customization UIs. This lets users record their own shortcuts by pressing the desired key combination, similar to how system preferences or IDE shortcut editors work.
+
+## Basic Usage
+
+```tsx
+import { createHotkeyRecorder, formatForDisplay } from '@tanstack/solid-hotkeys'
+
+function ShortcutRecorder() {
+ const recorder = createHotkeyRecorder({
+ onRecord: (hotkey) => {
+ console.log('Recorded:', hotkey) // e.g., "Mod+Shift+S"
+ },
+ })
+
+ return (
+
+
+
+
+
+
+ )
+}
+```
+
+> [!NOTE]
+> In Solid, `isRecording` and `recordedHotkey` are **accessors** (signal getters). You must call them with `()` to read the value: `recorder.isRecording()`, `recorder.recordedHotkey()`.
+
+## Return Value
+
+The `createHotkeyRecorder` primitive returns an object with:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isRecording` | `() => boolean` | Accessor returning whether the recorder is currently listening |
+| `recordedHotkey` | `() => Hotkey \| null` | Accessor returning the last recorded hotkey, or `null` |
+| `startRecording` | `() => void` | Start listening for key presses |
+| `stopRecording` | `() => void` | Stop listening and keep the recorded hotkey |
+| `cancelRecording` | `() => void` | Stop listening and discard any recorded hotkey |
+
+## Options
+
+```tsx
+createHotkeyRecorder({
+ onRecord: (hotkey) => { /* called when a hotkey is recorded */ },
+ onCancel: () => { /* called when recording is cancelled */ },
+ onClear: () => { /* called when the recorded hotkey is cleared */ },
+})
+```
+
+Options can also be passed as an accessor function for reactive configuration.
+
+### `onRecord`
+
+Called when the user presses a valid key combination. Receives the recorded `Hotkey` string.
+
+### `onCancel`
+
+Called when recording is cancelled (Escape or `cancelRecording()`).
+
+### `onClear`
+
+Called when the recorded hotkey is cleared (Backspace or Delete during recording).
+
+### Global Default Options via Provider
+
+```tsx
+import { HotkeysProvider } from '@tanstack/solid-hotkeys'
+
+ console.log('Recording cancelled'),
+ },
+ }}
+>
+
+
+```
+
+## Recording Behavior
+
+| Key | Behavior |
+|-----|----------|
+| **Modifier only** | Waits for a non-modifier key |
+| **Modifier + key** | Records the full combination |
+| **Single key** | Records the single key |
+| **Escape** | Cancels the recording |
+| **Backspace / Delete** | Clears the currently recorded hotkey |
+
+### Mod Auto-Conversion
+
+Recorded hotkeys automatically use the portable `Mod` format (Command on Mac, Control elsewhere).
+
+## Building a Shortcut Settings UI
+
+```tsx
+import { createSignal } from 'solid-js'
+import {
+ createHotkey,
+ createHotkeyRecorder,
+ formatForDisplay,
+} from '@tanstack/solid-hotkeys'
+import type { Hotkey } from '@tanstack/solid-hotkeys'
+
+function ShortcutSettings() {
+ const [shortcuts, setShortcuts] = createSignal>({
+ save: 'Mod+S',
+ undo: 'Mod+Z',
+ search: 'Mod+K',
+ })
+
+ const [editingAction, setEditingAction] = createSignal(null)
+
+ const recorder = createHotkeyRecorder({
+ onRecord: (hotkey) => {
+ const action = editingAction()
+ if (action) {
+ setShortcuts((prev) => ({ ...prev, [action]: hotkey }))
+ setEditingAction(null)
+ }
+ },
+ onCancel: () => setEditingAction(null),
+ })
+
+ // Register the actual hotkeys with their current bindings
+ createHotkey(() => shortcuts().save, () => save())
+ createHotkey(() => shortcuts().undo, () => undo())
+ createHotkey(() => shortcuts().search, () => openSearch())
+
+ return (
+
+
Keyboard Shortcuts
+
+ {([action, hotkey]) => (
+
+ {action}
+
+
+ )}
+
+
+ )
+}
+```
+
+## Under the Hood
+
+The `createHotkeyRecorder` primitive creates a `HotkeyRecorder` class instance and subscribes to its reactive state via `@tanstack/solid-store`. The class manages its own keyboard event listeners and state, and the primitive handles cleanup when the component is disposed.
diff --git a/docs/framework/solid/guides/hotkeys.md b/docs/framework/solid/guides/hotkeys.md
new file mode 100644
index 0000000..e84b8fd
--- /dev/null
+++ b/docs/framework/solid/guides/hotkeys.md
@@ -0,0 +1,241 @@
+---
+title: Hotkeys Guide
+id: hotkeys
+---
+
+The `createHotkey` primitive is the primary way to register keyboard shortcuts in SolidJS applications. It wraps the singleton `HotkeyManager` with automatic lifecycle management and reactive option support.
+
+## Basic Usage
+
+```tsx
+import { createHotkey } from '@tanstack/solid-hotkeys'
+
+function App() {
+ createHotkey('Mod+S', () => {
+ saveDocument()
+ }, {
+ // override the default options here
+ })
+}
+```
+
+The callback receives the original `KeyboardEvent` as the first argument and a `HotkeyCallbackContext` as the second:
+
+```tsx
+createHotkey('Mod+S', (event, context) => {
+ console.log(context.hotkey) // 'Mod+S'
+ console.log(context.parsedHotkey) // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+})
+```
+
+You can pass a hotkey as a string or as a `RawHotkey` object (modifier booleans optional). Use `mod` for cross-platform shortcuts (Command on Mac, Control elsewhere):
+
+```tsx
+createHotkey('Mod+S', () => save())
+createHotkey({ key: 'S', mod: true }, () => save()) // Same as above
+createHotkey({ key: 'Escape' }, () => closeModal())
+createHotkey({ key: 'S', ctrl: true, shift: true }, () => saveAs())
+createHotkey({ key: 'S', mod: true, shift: true }, () => saveAs())
+```
+
+## Reactive Options
+
+Unlike React/Preact hooks, Solid primitives accept **accessor functions** for reactive options. Pass a function that returns the options object to have the hotkey automatically update when dependencies change:
+
+```tsx
+function Modal(props) {
+ createHotkey('Escape', () => props.onClose(), () => ({
+ enabled: props.isOpen,
+ }))
+
+ return (
+
+
...
+
+ )
+}
+```
+
+For scoped targets, use an accessor so the hotkey waits for the element to be attached:
+
+```tsx
+function Editor() {
+ const [editorRef, setEditorRef] = createSignal(null)
+
+ createHotkey('Mod+S', save, () => ({ target: editorRef() }))
+
+ return
...
+}
+```
+
+## Default Options
+
+When you register a hotkey without passing options, or when you omit specific options, the following defaults apply:
+
+```tsx
+createHotkey('Mod+S', callback, {
+ enabled: true,
+ preventDefault: true,
+ stopPropagation: true,
+ eventType: 'keydown',
+ requireReset: false,
+ ignoreInputs: undefined, // smart default: false for Mod+S, true for single keys
+ target: document,
+ platform: undefined, // auto-detected
+ conflictBehavior: 'warn',
+})
+```
+
+### Why These Defaults?
+
+Most hotkey registrations are intended to override default browser behavior—such as using `Mod+S` to save a document instead of showing the browser's "Save Page" dialog. To make this easy and consistent, the library sets `preventDefault` and `stopPropagation` to `true` by default, ensuring your hotkey handlers take precedence and reducing the amount of repetitive boilerplate code required.
+
+#### Smart Input Handling: `ignoreInputs`
+
+The `ignoreInputs` option is designed to strike a balance between accessibility and usability. By default, hotkeys involving `Ctrl`/`Meta` modifiers (like `Mod+S`) and the `Escape` key are allowed to fire even when the focus is inside input elements (such as text fields or text areas), and when focused on button-type inputs (`type="button"`, `"submit"`, or `"reset"`). This allows shortcuts like save or close to work wherever the user is focused. On the other hand, single key shortcuts or those using only `Shift`/`Alt` are ignored within non-button inputs to prevent interference with normal typing.
+
+#### Hotkey Conflicts: `conflictBehavior`
+
+When you attempt to register a hotkey that is already registered (possibly in another part of your app), the library logs a warning by default using the `conflictBehavior: 'warn'` setting. This helps you catch accidental duplicate bindings during development so they can be resolved before reaching production.
+
+### Global Default Options via Provider
+
+You can change the default options for all `createHotkey` calls in your app by wrapping your component tree with `HotkeysProvider`. Per-primitive options will override the provider defaults.
+
+```tsx
+import { HotkeysProvider } from '@tanstack/solid-hotkeys'
+
+
+
+
+```
+
+## Hotkey Options
+
+### `enabled`
+
+Controls whether the hotkey is active. Defaults to `true`. Use an accessor for reactive control.
+
+```tsx
+const [isEditing, setIsEditing] = createSignal(false)
+
+createHotkey('Mod+S', () => save(), () => ({ enabled: isEditing() }))
+```
+
+### `preventDefault`
+
+Automatically calls `event.preventDefault()` when the hotkey fires. Defaults to `true`.
+
+```tsx
+createHotkey('Mod+S', () => save())
+createHotkey('Mod+S', () => save(), { preventDefault: false })
+```
+
+### `stopPropagation`
+
+Calls `event.stopPropagation()` when the hotkey fires. Defaults to `true`.
+
+```tsx
+createHotkey('Escape', () => closeModal())
+createHotkey('Escape', () => closeModal(), { stopPropagation: false })
+```
+
+### `eventType`
+
+Whether to listen on `keydown` (default) or `keyup`.
+
+```tsx
+createHotkey('Shift', () => deactivateMode(), { eventType: 'keyup' })
+```
+
+### `requireReset`
+
+When `true`, the hotkey will only fire once per key press. The key must be released and pressed again to fire again. Defaults to `false`.
+
+```tsx
+createHotkey('Escape', () => closePanel(), { requireReset: true })
+```
+
+### `ignoreInputs`
+
+When `true`, the hotkey will not fire when the user is focused on a text input, textarea, select, or contentEditable element. When unset, a smart default applies based on the hotkey type.
+
+```tsx
+createHotkey('K', () => openSearch()) // Smart default: ignored in inputs
+createHotkey('Mod+S', () => save()) // Smart default: fires in inputs
+createHotkey('Enter', () => submit(), { ignoreInputs: false })
+```
+
+### `target`
+
+The DOM element to attach the event listener to. Defaults to `document`. Can be a DOM element, `document`, `window`, or from an accessor for reactive targets.
+
+```tsx
+const [panelRef, setPanelRef] = createSignal(null)
+
+createHotkey('Escape', () => closePanel(), () => ({ target: panelRef() }))
+
+return
...
+```
+
+> [!NOTE]
+> When using an accessor for the target, the primitive waits for the element to be available before registering. Ensure the element is focusable (has `tabIndex`) so it can receive keyboard events.
+
+### `conflictBehavior`
+
+Controls what happens when you register a hotkey that's already registered. Options: `'warn'`, `'error'`, `'replace'`, `'allow'`.
+
+```tsx
+createHotkey('Mod+S', () => save(), { conflictBehavior: 'replace' })
+```
+
+### `platform`
+
+Override the auto-detected platform.
+
+```tsx
+createHotkey('Mod+S', () => save(), { platform: 'mac' })
+```
+
+## Automatic Dependency Tracking
+
+Solid's fine-grained reactivity means `createHotkey` automatically tracks reactive dependencies. The callback always has access to the latest signal values:
+
+```tsx
+function Counter() {
+ const [count, setCount] = createSignal(0)
+
+ createHotkey('Mod+Shift+C', () => {
+ console.log('Current count:', count())
+ })
+
+ return
+}
+```
+
+## Automatic Cleanup
+
+The primitive automatically unregisters the hotkey when the component unmounts (when the owning reactive scope is disposed):
+
+```tsx
+function TemporaryPanel() {
+ createHotkey('Escape', () => closePanel())
+ return
Panel content
+}
+```
+
+## The Hotkey Manager
+
+Under the hood, `createHotkey` uses the singleton `HotkeyManager`. You can also access the manager directly if needed:
+
+```tsx
+import { getHotkeyManager } from '@tanstack/solid-hotkeys'
+
+const manager = getHotkeyManager()
+manager.isRegistered('Mod+S')
+manager.getRegistrationCount()
+```
diff --git a/docs/framework/solid/guides/key-state-tracking.md b/docs/framework/solid/guides/key-state-tracking.md
new file mode 100644
index 0000000..92768f2
--- /dev/null
+++ b/docs/framework/solid/guides/key-state-tracking.md
@@ -0,0 +1,188 @@
+---
+title: Key State Tracking Guide
+id: key-state-tracking
+---
+
+TanStack Hotkeys provides three primitives for tracking the real-time state of keyboard keys. These are useful for building UIs that respond to modifier keys being held, displaying active key states, or implementing hold-to-activate features.
+
+## `createHeldKeys`
+
+Returns an accessor that yields an array of all currently held key names.
+
+```tsx
+import { createHeldKeys } from '@tanstack/solid-hotkeys'
+
+function KeyDisplay() {
+ const heldKeys = createHeldKeys()
+
+ return (
+
+ )
+}
+```
+
+> [!NOTE]
+> In Solid, `createHeldKeys()` returns an **accessor function**. Call it with `()` to read the current value: `heldKeys()`.
+
+The returned array contains key names like `'Shift'`, `'Control'`, `'Meta'`, `'A'`, `'ArrowUp'`, etc. Keys appear in the order they were pressed.
+
+## `createHeldKeyCodes`
+
+Returns an accessor that yields a reactive object mapping held key names to their physical key codes (`event.code` values). Useful for distinguishing between left and right modifiers.
+
+```tsx
+import { createHeldKeyCodes } from '@tanstack/solid-hotkeys'
+
+function KeyCodeDisplay() {
+ const heldCodes = createHeldKeyCodes()
+ // Example: { Shift: "ShiftLeft", Control: "ControlRight" }
+
+ return (
+
+
+ {([key, code]) => (
+
+ {key}: {code}
+
+ )}
+
+
+ )
+}
+```
+
+## `createKeyHold`
+
+Returns an accessor that indicates whether a specific key is currently held. Optimized to only trigger updates when the specified key's held state changes. The `key` argument can be a string or an accessor for reactive keys.
+
+```tsx
+import { createKeyHold } from '@tanstack/solid-hotkeys'
+
+function ModifierIndicators() {
+ const isShiftHeld = createKeyHold('Shift')
+ const isCtrlHeld = createKeyHold('Control')
+ const isAltHeld = createKeyHold('Alt')
+ const isMetaHeld = createKeyHold('Meta')
+
+ return (
+
+ Shortcuts can be scoped to specific DOM elements using the{' '}
+ target option. This allows different shortcuts to work
+ in different parts of your application.
+