TanStack Hotkeys

https://tanstack.com/hotkeys/latest
Admin
TanStack Hotkeys is a type-safe, framework-agnostic library for handling keyboard shortcuts,...
Tokens:109,891
Snippets:1,333
Trust Score:9.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### start()

Source: https://tanstack.com/hotkeys/latest/docs/reference/classes/HotkeyRecorder.md

Starts the keyboard event listener to begin capturing a hotkey.

```APIDOC
## Method: start()

### Description
Begins recording a new hotkey by attaching a keydown event listener. Recording continues until a valid hotkey is captured, Escape is pressed, or the process is manually stopped or cancelled.
```

--------------------------------

### Install Solid Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Install the required packages for Solid applications.

```sh
npm install @tanstack/solid-devtools @tanstack/solid-hotkeys-devtools
```

--------------------------------

### formatForDisplay Usage Examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/formatForDisplay.md

Examples demonstrating how to format hotkeys for different platforms and keys.

```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)
```

--------------------------------

### startRecording()

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeyRecorderController

Starts the hotkey recording process.

```APIDOC
## startRecording()

### Description
Initiates the recording of a new hotkey.
```

--------------------------------

### normalizeHotkey usage examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/normalizeHotkey.md

Examples demonstrating how to normalize various hotkey strings for different platforms.

```ts
normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
normalizeHotkey('esc') // 'Escape'
```

--------------------------------

### normalizeKeyName usage examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/isSingleLetterKey

Examples demonstrating how to normalize various key name formats into their canonical forms.

```ts
normalizeKeyName('esc') // 'Escape'
normalizeKeyName('a') // 'A'
normalizeKeyName('f1') // 'F1'
normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
```

--------------------------------

### Usage Examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/hasNonModifierKey

Examples demonstrating how to check hotkey strings and parsed hotkey objects for non-modifier keys.

```ts
hasNonModifierKey('Control+Shift+S') // true
hasNonModifierKey('Control+Shift') // false (no action key)
hasNonModifierKey(parseHotkey('Mod+A')) // true
```

--------------------------------

### formatHotkeySequence Usage Examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/formatHotkeySequence

Examples demonstrating how to convert hotkey sequence arrays into space-separated strings.

```ts
formatHotkeySequence(['G', 'G'])      // 'G G'
formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
```

--------------------------------

### Install React Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Install the required packages for React applications.

```sh
npm install @tanstack/react-devtools @tanstack/react-hotkeys-devtools
```

--------------------------------

### Start Recording Method

Source: https://tanstack.com/hotkeys/latest/docs/framework/angular/reference/interfaces/AngularHotkeyRecorder

Initiates a new hotkey recording session.

```ts
readonly startRecording: () => void;
```

--------------------------------

### Install Preact Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Install the required packages for Preact applications.

```sh
npm install @tanstack/preact-devtools @tanstack/preact-hotkeys-devtools
```

--------------------------------

### Define HotkeySequence examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/type-aliases/HotkeySequence.md

Examples showing how to define various Vim-style shortcut sequences using the HotkeySequence type.

```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']
```

--------------------------------

### validateHotkey Usage Examples

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/validateHotkey

Examples demonstrating valid and invalid hotkey string validation results.

```ts
validateHotkey('Mod+S')
// { valid: true, warnings: [], errors: [] }

validateHotkey('')
// { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
```

--------------------------------

### createHotkeyHandler usage example

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/createHotkeyHandler

Example of creating a handler for the 'Mod+S' shortcut and attaching it to the document.

```ts
const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
  console.log(`${hotkey} was pressed`)
  handleSave()
})

document.addEventListener('keydown', handler)
```

--------------------------------

### Initialize and use HotkeyRecorder

Source: https://tanstack.com/hotkeys/latest/docs/reference/classes/HotkeyRecorder.md

Demonstrates instantiating the recorder, starting the capture process, accessing state, and performing cleanup.

```ts
const recorder = new HotkeyRecorder({
  onRecord: (hotkey) => {
    console.log('Recorded:', hotkey)
  },
  onCancel: () => {
    console.log('Recording cancelled')
  },
})

// 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)
})

// Cleanup
recorder.destroy()
unsubscribe()
```

--------------------------------

### useKeyHold usage examples

Source: https://tanstack.com/hotkeys/latest/docs/framework/react/reference/functions/useKeyHold

Examples demonstrating how to use the hook to track single or multiple modifier keys.

```tsx
function ShiftIndicator() {
  const isShiftHeld = useKeyHold('Shift')

  return (
    <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
      {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
    </div>
  )
}
```

```tsx
function ModifierIndicators() {
  const ctrl = useKeyHold('Control')
  const shift = useKeyHold('Shift')
  const alt = useKeyHold('Alt')

  return (
    <div>
      <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
      <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
      <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
    </div>
  )
}
```

--------------------------------

### Implement Vim-style navigation

Source: https://tanstack.com/hotkeys/latest/docs/framework/angular/guides/sequences.md

Example of registering multiple navigation-related sequences.

```ts
injectHotkeySequence(['G', 'G'], () => scrollToTop())
injectHotkeySequence(['G', 'Shift+G'], () => scrollToBottom())
injectHotkeySequence(['D', 'D'], () => deleteLine())
injectHotkeySequence(['D', 'W'], () => deleteWord())
injectHotkeySequence(['C', 'I', 'W'], () => changeInnerWord())
```

--------------------------------

### Setup Solid Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Integrate the hotkeys plugin into the TanStack Devtools component for Solid.

```tsx
import { TanStackDevtools } from '@tanstack/solid-devtools'
import { hotkeysDevtoolsPlugin } from '@tanstack/solid-hotkeys-devtools'

export function App() {
  return <TanStackDevtools plugins={[hotkeysDevtoolsPlugin()]} />
}
```

--------------------------------

### Install Vue Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Install the required package for Vue applications.

```sh
npm install @tanstack/vue-hotkeys-devtools
```

--------------------------------

### Start recording method

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeySequenceRecorderController

Initiates a new sequence recording session.

```ts
startRecording(): void;
```

--------------------------------

### Implement ShortcutSettings component

Source: https://tanstack.com/hotkeys/latest/docs/framework/solid/reference/functions/createHotkeyRecorder

Usage example demonstrating how to integrate createHotkeyRecorder within a SolidJS component to capture and display keyboard shortcuts.

```tsx
function ShortcutSettings() {
  const [shortcut, setShortcut] = createSignal<Hotkey>('Mod+S')

  const recorder = createHotkeyRecorder({
    onRecord: (hotkey) => {
      setShortcut(hotkey)
    },
    onCancel: () => {
      console.log('Recording cancelled')
    },
  })

  return (
    <div>
      <button onClick={recorder.startRecording}>
        {recorder.isRecording() ? 'Recording...' : 'Edit Shortcut'}
      </button>
      <Show when={recorder.recordedHotkey()}>
        <div>Recording: {recorder.recordedHotkey()}</div>
      </Show>
    </div>
  )
}
```

--------------------------------

### Usage Example for createSequenceMatcher

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/createSequenceMatcher.md

Demonstrates how to initialize a matcher for a 'G', 'G' sequence and use it within a keydown event listener.

```ts
const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })

document.addEventListener('keydown', (event) => {
  if (matcher.match(event)) {
    console.log('Sequence matched!')
  }
})
```

--------------------------------

### Implement a Shortcut Recorder with useHotkeyRecorder

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/guides/hotkey-recording.md

This example demonstrates how to integrate the hook into a component to toggle recording state and handle the captured hotkey.

```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 (
    <div>
      <button onClick={isRecording ? stopRecording : startRecording}>
        {isRecording
          ? 'Press a key combination...'
          : recordedHotkey
            ? formatForDisplay(recordedHotkey)
            : 'Click to record'}
      </button>
      {isRecording && (
        <button onClick={cancelRecording}>Cancel</button>
      )}
    </div>
  )
}
```

--------------------------------

### Usage example for detectPlatform

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/detectPlatform

Demonstrates how to use the detected platform to resolve platform-specific modifiers.

```ts
const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
```

--------------------------------

### Using createKeyHold for a single key

Source: https://tanstack.com/hotkeys/latest/docs/framework/solid/reference/functions/createKeyHold

Example showing how to track the Shift key state to toggle UI opacity.

```tsx
function ShiftIndicator() {
  const isShiftHeld = createKeyHold('Shift')

  return (
    <div style={{ opacity: isShiftHeld() ? 1 : 0.5 }}>
      {isShiftHeld() ? 'Shift is pressed!' : 'Press Shift'}
    </div>
  )
}
```

--------------------------------

### Setup React Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Integrate the hotkeys plugin into the TanStack Devtools component.

```tsx
import { TanStackDevtools } from '@tanstack/react-devtools'
import { hotkeysDevtoolsPlugin } from '@tanstack/react-hotkeys-devtools'

function App() {
  return <TanStackDevtools plugins={[hotkeysDevtoolsPlugin()]} />
}
```

--------------------------------

### Usage Examples for rawHotkeyToParsedHotkey

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/rawHotkeyToParsedHotkey

Demonstrates converting various raw hotkey configurations into parsed objects for different platforms.

```ts
rawHotkeyToParsedHotkey({ key: 'Escape' })
// { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }

rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
// { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }

rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
// { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
```

--------------------------------

### checkHotkey Usage Example

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/checkHotkey

Demonstrates validating a hotkey string and the resulting console output.

```ts
checkHotkey('Alt+C')
// Console: Warning: Alt+C may not work reliably on macOS...
// Returns: true
```

--------------------------------

### Setup Preact Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Integrate the hotkeys plugin into the TanStack Devtools component for Preact.

```tsx
import { TanStackDevtools } from '@tanstack/preact-devtools'
import { hotkeysDevtoolsPlugin } from '@tanstack/preact-hotkeys-devtools'

export function App() {
  return <TanStackDevtools plugins={[hotkeysDevtoolsPlugin()]} />
}
```

--------------------------------

### Implement Konami code

Source: https://tanstack.com/hotkeys/latest/docs/framework/angular/guides/sequences.md

Example of a longer sequence with a custom timeout.

```ts
injectHotkeySequence(
  ['ArrowUp', 'ArrowUp', 'ArrowDown', 'ArrowDown', 'B', 'A'],
  () => enableEasterEgg(),
  { timeout: 2000 },
)
```

--------------------------------

### Implementing a hotkey recorder in Preact

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/reference/functions/useHotkeyRecorder

Example showing how to use the hook to manage shortcut recording state and handle recording lifecycle events.

```tsx
function ShortcutSettings() {
  const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')

  const recorder = useHotkeyRecorder({
    onRecord: (hotkey) => {
      setShortcut(hotkey)
    },
    onCancel: () => {
      console.log('Recording cancelled')
    },
  })

  return (
    <div>
      <button onClick={recorder.startRecording}>
        {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
      </button>
      {recorder.recordedHotkey && (
        <div>Recording: {recorder.recordedHotkey}</div>
      )}
    </div>
  )
}
```

--------------------------------

### Implement a basic hotkey sequence recorder

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/guides/sequence-recording.md

Demonstrates the basic setup of the useHotkeySequenceRecorder hook to capture and display sequences.

```tsx
import { useHotkeySequenceRecorder, formatForDisplay } from '@tanstack/preact-hotkeys'
import type { HotkeySequence } from '@tanstack/preact-hotkeys'

function HotkeySequenceRecorder() {
  const recorder = useHotkeySequenceRecorder({
    onRecord: (sequence: HotkeySequence) => {
      console.log('Recorded:', sequence)
    },
  })

  return (
    <div>
      <button
        type="button"
        onClick={
          recorder.isRecording ? recorder.cancelRecording : recorder.startRecording
        }
      >
        {recorder.isRecording
          ? 'Press chords, then Enter…'
          : recorder.recordedSequence
            ? recorder.recordedSequence.map((h) => formatForDisplay(h)).join(' ')
            : 'Click to record'}
      </button>
      {recorder.isRecording && (
        <button type="button" onClick={recorder.cancelRecording}>
          Cancel
        </button>
      )}
    </div>
  )
}
```

--------------------------------

### provideHotkeysContext(defaultOptions?)

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/reference/functions/provideHotkeysContext.md

Initializes the hotkeys context for the application. This function should be called within a Vue setup context to provide configuration options to child components.

```APIDOC
## provideHotkeysContext(defaultOptions?)

### Description
Initializes the hotkeys context for the application. This function allows you to set default options for hotkey handling throughout the component tree.

### Signature
`function provideHotkeysContext(defaultOptions?: HotkeysProviderOptions): void;`

### Parameters
- **defaultOptions** (HotkeysProviderOptions) - Optional - Configuration options for the hotkeys provider.

### Returns
- **void**
```

--------------------------------

### Using createKeyHold for multiple modifiers

Source: https://tanstack.com/hotkeys/latest/docs/framework/solid/reference/functions/createKeyHold

Example showing how to track multiple modifier keys simultaneously.

```tsx
function ModifierIndicators() {
  const ctrl = createKeyHold('Control')
  const shift = createKeyHold('Shift')
  const alt = createKeyHold('Alt')

  return (
    <div>
      <span style={{ opacity: ctrl() ? 1 : 0.3 }}>Ctrl</span>
      <span style={{ opacity: shift() ? 1 : 0.3 }}>Shift</span>
      <span style={{ opacity: alt() ? 1 : 0.3 }}>Alt</span>
    </div>
  )
}
```

--------------------------------

### Tracking multiple keys

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/reference/functions/useKeyHold.md

Example showing how to track multiple modifier keys simultaneously.

```vue
<script setup>
import { useKeyHold } from '@tanstack/vue-hotkeys'

const ctrl = useKeyHold('Control')
const shift = useKeyHold('Shift')
const alt = useKeyHold('Alt')
</script>

<template>
  <div>
    <span :style="{ opacity: ctrl ? 1 : 0.3 }">Ctrl</span>
    <span :style="{ opacity: shift ? 1 : 0.3 }">Shift</span>
    <span :style="{ opacity: alt ? 1 : 0.3 }">Alt</span>
  </div>
</template>
```

--------------------------------

### Accessing key symbols

Source: https://tanstack.com/hotkeys/latest/docs/reference/variables/KEY_DISPLAY_SYMBOLS.md

Example usage showing how to retrieve visual symbols from the KEY_DISPLAY_SYMBOLS object.

```ts
KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
KEY_DISPLAY_SYMBOLS['Space'] // '␣'
```

--------------------------------

### Example Usage of createMultiHotkeyHandler

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/createMultiHotkeyHandler

Demonstrates mapping multiple hotkey combinations to specific handler functions and attaching the result to the document.

```ts
const handler = createMultiHotkeyHandler({
  'Mod+S': (event, { hotkey }) => handleSave(),
  'Mod+Z': (event, { hotkey }) => handleUndo(),
  'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
})

document.addEventListener('keydown', handler)
```

--------------------------------

### Implementing a hotkey recorder in a Vue component

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/reference/functions/useHotkeyRecorder.md

A complete example showing how to initialize the recorder and bind its state and control methods to a component template.

```vue
<script setup>
import { ref } from 'vue'
import { useHotkeyRecorder } from '@tanstack/vue-hotkeys'

const shortcut = ref<Hotkey>('Mod+S')

const recorder = useHotkeyRecorder({
  onRecord: (hotkey) => {
    shortcut.value = hotkey
  },
  onCancel: () => {
    console.log('Recording cancelled')
  },
})
</script>

<template>
  <div>
    <button @click="recorder.startRecording()">
      {{ recorder.isRecording ? 'Recording...' : 'Edit Shortcut' }}
    </button>
    <div v-if="recorder.recordedHotkey">
      Recording: {{ recorder.recordedHotkey }}
    </div>
  </div>
</template>
```

--------------------------------

### Implement hotkey sequences in Vue

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/reference/functions/useHotkeySequence.md

Examples of registering various key sequences including simple repeats, multi-key commands, and sequences with modifiers.

```vue
<script setup>
import { useHotkeySequence } from '@tanstack/vue-hotkeys'

// 'g g' to go to top
useHotkeySequence(['G', 'G'], () => {
  scrollToTop()
})

// 'd d' to delete line
useHotkeySequence(['D', 'D'], () => {
  deleteLine()
})

// 'd i w' to delete inner word
useHotkeySequence(['D', 'I', 'W'], () => {
  deleteInnerWord()
}, { timeout: 500 })

// Same modifier on consecutive steps (bare Shift between chords is ignored)
useHotkeySequence(['Shift+R', 'Shift+T'], () => {
  nextAction()
})
</script>

<template>
  <div>...</div>
</template>
```

--------------------------------

### Parsing Hotkey Strings

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/parseHotkey

Examples showing how hotkey strings are parsed into objects, including platform-specific resolution for 'Mod'.

```ts
parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
```

--------------------------------

### Usage Example for assertValidHotkey

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/assertValidHotkey

Demonstrates successful validation and an error-throwing scenario for an empty hotkey string.

```ts
assertValidHotkey('Mod+S') // OK
assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
```

--------------------------------

### Usage Example for matchesKeyboardEvent

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/matchesKeyboardEvent

Demonstrates how to use matchesKeyboardEvent within a keydown event listener to trigger an action.

```ts
document.addEventListener('keydown', (event) => {
  if (matchesKeyboardEvent(event, 'Mod+S')) {
    event.preventDefault()
    handleSave()
  }
})
```

--------------------------------

### Tracking multiple key states

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference/functions/getIsKeyHeld

Example demonstrating how to track multiple modifier keys simultaneously to update UI elements.

```svelte
<script>
  import { getIsKeyHeld } from '@tanstack/svelte-hotkeys'

  const isCtrlHeld = getIsKeyHeld('Control')
  const isShiftHeld = getIsKeyHeld('Shift')
  const isAltHeld = getIsKeyHeld('Alt')
</script>

<div>
  <span style:opacity={isCtrlHeld.held ? 1 : 0.3}>Ctrl</span>
  <span style:opacity={isShiftHeld.held ? 1 : 0.3}>Shift</span>
  <span style:opacity={isAltHeld.held ? 1 : 0.3}>Alt</span>
</div>
```

--------------------------------

### new HotkeyRecorderController(host, options)

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeyRecorderController

Initializes a new instance of the HotkeyRecorderController.

```APIDOC
## Constructor

### Description
Creates a new HotkeyRecorderController instance attached to a Lit component.

### Parameters
- **_host** (ReactiveControllerHost) - The Lit component that owns this controller.
- **_options** (HotkeyRecorderOptions) - Configuration options for the recorder.
```

--------------------------------

### Tracking a single key

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/reference/functions/useKeyHold.md

Example showing how to track the Shift key and update UI based on its state.

```vue
<script setup>
import { useKeyHold } from '@tanstack/vue-hotkeys'

const isShiftHeld = useKeyHold('Shift')
</script>

<template>
  <div :style="{ opacity: isShiftHeld ? 1 : 0.5 }">
    {{ isShiftHeld ? 'Shift is pressed!' : 'Press Shift' }}
  </div>
</template>
```

--------------------------------

### Implement Shift key indicator

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/reference/functions/useKeyHold

Example showing how to use useKeyHold to toggle UI visibility based on the Shift key state.

```tsx
function ShiftIndicator() {
  const isShiftHeld = useKeyHold('Shift')

  return (
    <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
      {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
    </div>
  )
}
```

--------------------------------

### Using hotkeySequence in a LitElement

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/functions/hotkeySequence

Example showing how to apply the decorator to class methods to trigger actions on specific key sequences.

```ts
class MyElement extends LitElement {
  @hotkeySequence(['G', 'G'])
  goToTop() { window.scrollTo(0, 0) }

  @hotkeySequence(['D', 'D'], { timeout: 500 })
  deleteLine() { this.deleteCurrentLine() }
}
```

--------------------------------

### Displaying hotkeys and sequences

Source: https://tanstack.com/hotkeys/latest/docs/framework/react/reference/functions/useHotkeyRegistrations

Example of using the hook to map and display registered hotkeys and sequences in a component.

```tsx
function ShortcutPalette() {
  const { hotkeys, sequences } = useHotkeyRegistrations()

  return (
    <ul>
      {hotkeys.map((reg) => (
        <li key={reg.id}>
          {reg.options.meta?.name ?? reg.hotkey}
        </li>
      ))}
      {sequences.map((reg) => (
        <li key={reg.id}>
          {reg.options.meta?.name ?? reg.sequence.join(' ')}
        </li>
      ))}
    </ul>
  )
}
```

--------------------------------

### Usage of createHotkeySequence in Svelte

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference/functions/createHotkeySequence

Examples of registering various keyboard sequences including multi-key chords and custom timeout options.

```svelte
<script lang="ts">
  import { createHotkeySequence } from '@tanstack/svelte-hotkeys'

  // Scroll to top when 'G G' is pressed
  createHotkeySequence(['G', 'G'], () => {
    scrollToTop()
  })

  // Delete line when 'D D' is pressed
  createHotkeySequence(['D', 'D'], () => {
    deleteLine()
  })

  // Delete inner word when 'D I W' is pressed
  createHotkeySequence(['D', 'I', 'W'], () => {
    deleteInnerWord()
  }, { timeout: 500 })

  // Same modifier on consecutive steps (bare Shift between chords is ignored)
  createHotkeySequence(['Shift+R', 'Shift+T'], () => {
    nextAction()
  })
</script>

<div>
  ....
</div>
```

--------------------------------

### createHotkeySequenceRecorder(options)

Source: https://tanstack.com/hotkeys/latest/docs/framework/solid/reference/functions/createHotkeySequenceRecorder

Initializes a recorder for multi-chord hotkey sequences in a SolidJS application.

```APIDOC
## createHotkeySequenceRecorder(options)

### Description
A SolidJS primitive used for recording multi-chord sequences, such as Vim-style shortcuts.

### Signature
`function createHotkeySequenceRecorder(options): SolidHotkeySequenceRecorder;`

### Parameters
- **options** (HotkeySequenceRecorderOptions | () => HotkeySequenceRecorderOptions) - Configuration options or a function returning configuration options for the recorder.

### Returns
- **SolidHotkeySequenceRecorder** - An object representing the hotkey sequence recorder instance.
```

--------------------------------

### Using KeyStateTracker

Source: https://tanstack.com/hotkeys/latest/docs/reference/classes/KeyStateTracker.md

Demonstrates how to access the singleton instance, subscribe to state changes, and query held keys.

```ts
const tracker = KeyStateTracker.getInstance()

// Access state directly
console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']

// Subscribe to changes with TanStack Store
const unsubscribe = tracker.store.subscribe(() => {
  console.log('Currently held:', tracker.store.state.heldKeys)
})

// Check current state
console.log(tracker.getHeldKeys()) // ['Control', 'Shift']
console.log(tracker.isKeyHeld('Control')) // true

// Cleanup
unsubscribe()
```

--------------------------------

### Get KeyStateTracker instance

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/getKeyStateTracker.md

Access the singleton instance of the KeyStateTracker.

```ts
function getKeyStateTracker(): KeyStateTracker;
```

--------------------------------

### createHotkeyRecorder(options)

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference/functions/createHotkeyRecorder

Initializes a new hotkey recorder instance. It accepts an options object and returns a SvelteHotkeyRecorder interface.

```APIDOC
## createHotkeyRecorder(options)

### Description
Initializes a hotkey recorder instance to manage keyboard shortcut capturing in a Svelte component.

### Signature
`function createHotkeyRecorder(options: MaybeGetter<HotkeyRecorderOptions>): SvelteHotkeyRecorder`

### Parameters
- **options** (MaybeGetter<HotkeyRecorderOptions>) - Required - Configuration options for the hotkey recorder.

### Returns
- **SvelteHotkeyRecorder** - An instance of the hotkey recorder interface.
```

--------------------------------

### Initialize HotkeySequenceRecorderController

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/guides/sequence-recording.md

Instantiate the controller with callback handlers and configuration options for recording behavior.

```ts
new HotkeySequenceRecorderController(this, {
  onRecord: (sequence) => { /* called when a sequence is committed */ },
  onCancel: () => { /* called when recording is cancelled */ },
  onClear: () => { /* called when cleared via Backspace with no steps */ },
  commitKeys: 'enter', // or 'none'
  idleTimeoutMs: 2000,
})
```

--------------------------------

### createHotkeySequenceRecorder(options)

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference/functions/createHotkeySequenceRecorder

Initializes a Svelte hotkey sequence recorder for capturing multi-chord input sequences.

```APIDOC
## createHotkeySequenceRecorder(options)

### Description
Initializes a Svelte helper for recording multi-chord sequences, commonly used for Vim-style shortcuts.

### Signature
`function createHotkeySequenceRecorder(options: MaybeGetter<HotkeySequenceRecorderOptions>): SvelteHotkeySequenceRecorder`

### Parameters
- **options** (MaybeGetter<HotkeySequenceRecorderOptions>) - Required - Configuration options for the hotkey sequence recorder.

### Returns
- **SvelteHotkeySequenceRecorder** - An instance of the SvelteHotkeySequenceRecorder interface.
```

--------------------------------

### Initialize HotkeyRecorderController

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/guides/hotkey-recording.md

Pass configuration options to the constructor to handle recording lifecycle events.

```ts
new HotkeyRecorderController(this, {
  onRecord: (hotkey) => { /* called when a hotkey is recorded */ },
  onCancel: () => { /* called when recording is cancelled */ },
  onClear: () => { /* called when the recorded hotkey is cleared */ },
})
```

--------------------------------

### formatHotkey Usage Example

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/formatHotkey.md

Converts a ParsedHotkey object into a canonical string format.

```ts
formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
// Returns: 'Control+Shift+S'
```

--------------------------------

### Getting registration count

Source: https://tanstack.com/hotkeys/latest/docs/reference/classes/SequenceManager.md

Retrieve the total number of currently registered sequences.

```ts
getRegistrationCount(): number;
```

--------------------------------

### Record user shortcuts

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/quick-start.md

Use createHotkeyRecorder to capture user input and format it for display.

```svelte
<script lang="ts">
  import {
    createHotkeyRecorder,
    formatForDisplay,
  } from '@tanstack/svelte-hotkeys'

  const recorder = createHotkeyRecorder({
    onRecord: (hotkey) => {
      console.log('Recorded:', hotkey)
    },
  })
</script>

<button onclick={recorder.startRecording}>
  {recorder.recordedHotkey
    ? formatForDisplay(recorder.recordedHotkey)
    : 'Click to record'}
</button>
```

--------------------------------

### Get steps accessor

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeySequenceRecorderController

Returns the chords captured in the current recording session.

```ts
get steps(): HotkeySequence;
```

--------------------------------

### Get isRecording accessor

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeySequenceRecorderController

Returns a boolean indicating if recording is currently active.

```ts
get isRecording(): boolean;
```

--------------------------------

### Setup Vue Devtools

Source: https://tanstack.com/hotkeys/latest/docs/devtools.md

Add the HotkeysDevtoolsPanel component to your Vue application template.

```vue
<script setup lang="ts">
import { HotkeysDevtoolsPanel } from '@tanstack/vue-hotkeys-devtools'
</script>

<template>
  <AppContent />
  <HotkeysDevtoolsPanel />
</template>
```

--------------------------------

### Implement HotkeyCallback handler

Source: https://tanstack.com/hotkeys/latest/docs/reference/type-aliases/HotkeyCallback.md

Example implementation of a handler function using the HotkeyCallback type.

```ts
const handler: HotkeyCallback = (event, { hotkey, parsedHotkey }) => {
  console.log(`Hotkey ${hotkey} was pressed`)
  console.log(`Modifiers:`, parsedHotkey.modifiers)
}
```

--------------------------------

### setHotkeysContext(defaultOptions)

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference/functions/setHotkeysContext

Initializes the hotkeys context with the provided default options.

```APIDOC
## setHotkeysContext

### Signature
`function setHotkeysContext(defaultOptions: HotkeysProviderOptions): HotkeysContextValue`

### Description
Initializes the hotkeys context for the application. This function should be used to set the default configuration for hotkey handling.

### Parameters
- **defaultOptions** (HotkeysProviderOptions) - Required - The configuration options for the hotkeys provider, defaulting to DEFAULT_OPTIONS.

### Returns
- **HotkeysContextValue** - The context value containing the hotkeys state and configuration.
```

--------------------------------

### useHeldKeys usage example

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/reference/functions/useHeldKeys.md

Displays the currently held keys in a Vue component template.

```vue
<script setup>
import { useHeldKeys } from '@tanstack/vue-hotkeys'

const heldKeys = useHeldKeys()
</script>

<template>
  <div>
    Currently pressed: {{ heldKeys.join(' + ') || 'None' }}
  </div>
</template>
```

--------------------------------

### Implementing Vim-style sequences with useHotkeySequence

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/reference/functions/useHotkeySequence

Demonstrates registering various multi-key sequences, including those with custom timeouts and modifier keys.

```tsx
function VimEditor() {
  // 'g g' to go to top
  useHotkeySequence(['G', 'G'], () => {
    scrollToTop()
  })

  // 'd d' to delete line
  useHotkeySequence(['D', 'D'], () => {
    deleteLine()
  })

  // 'd i w' to delete inner word
  useHotkeySequence(['D', 'I', 'W'], () => {
    deleteInnerWord()
  }, { timeout: 500 })

  // Same modifier on consecutive steps (bare Shift between chords is ignored)
  useHotkeySequence(['Shift+R', 'Shift+T'], () => {
    nextAction()
  })

  return <div>...</div>
}
```

--------------------------------

### Get HotkeyManager Instance

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/getHotkeyManager.md

Access the singleton HotkeyManager instance using this convenience function.

```ts
function getHotkeyManager(): HotkeyManager;
```

--------------------------------

### new HotkeySequenceRecorderController(host, options)

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeySequenceRecorderController

Initializes a new instance of the HotkeySequenceRecorderController to manage sequence recording within a Lit component.

```APIDOC
## Constructor

### Description
Creates a new HotkeySequenceRecorderController instance attached to a Lit component host.

### Signature
`new HotkeySequenceRecorderController(host: ReactiveControllerHost, options: HotkeySequenceRecorderOptions)`

### Parameters
- **host** (ReactiveControllerHost) - The Lit component instance that owns the controller.
- **options** (HotkeySequenceRecorderOptions) - Configuration object containing callbacks like onRecord and onCancel.
```

--------------------------------

### Get recordedSequence accessor

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeySequenceRecorderController

Returns the last committed sequence or null if none exists.

```ts
get recordedSequence(): HotkeySequence | null;
```

--------------------------------

### HotkeySequenceRecorderController Constructor

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeySequenceRecorderController

Initialize the controller by passing the host component and configuration options.

```ts
new HotkeySequenceRecorderController(_host, _options): HotkeySequenceRecorderController;
```

--------------------------------

### new HotkeyRecorder(options)

Source: https://tanstack.com/hotkeys/latest/docs/reference/classes/HotkeyRecorder.md

Creates a new instance of the HotkeyRecorder class with the provided configuration options.

```APIDOC
## Constructor

### Description
Initializes a new HotkeyRecorder instance.

### Signature
`new HotkeyRecorder(options: HotkeyRecorderOptions): HotkeyRecorder`

### Parameters
- **options** (HotkeyRecorderOptions) - Required - Configuration object containing callbacks like onRecord and onCancel.
```

--------------------------------

### Access MODIFIER_ALIASES mappings

Source: https://tanstack.com/hotkeys/latest/docs/reference/variables/MODIFIER_ALIASES.md

Examples of retrieving canonical modifier names using common aliases.

```ts
MODIFIER_ALIASES['Ctrl'] // 'Control'
MODIFIER_ALIASES['Cmd'] // 'Meta'
MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)
```

--------------------------------

### Access macOS modifier labels

Source: https://tanstack.com/hotkeys/latest/docs/reference/variables/MAC_MODIFIER_LABELS.md

Examples of accessing specific modifier labels for macOS display.

```ts
MAC_MODIFIER_LABELS['Control'] // 'control'
MAC_MODIFIER_LABELS['Alt'] // 'option'
MAC_MODIFIER_LABELS['Shift'] // 'shift'
MAC_MODIFIER_LABELS['Meta'] // 'cmd'
```

--------------------------------

### useHotkeyRecorder(options)

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/reference/functions/useHotkeyRecorder

Initializes a hotkey recorder instance for capturing user keyboard input in Preact components.

```APIDOC
## useHotkeyRecorder(options)

### Description
A Preact hook that provides a wrapper around the framework-agnostic HotkeyRecorder class to manage keyboard shortcut recording.

### Signature
`function useHotkeyRecorder(options: HotkeyRecorderOptions): PreactHotkeyRecorder`

### Parameters
- **options** (HotkeyRecorderOptions) - Configuration options for the recorder, including callbacks like onRecord and onCancel.

### Returns
- **PreactHotkeyRecorder** - An object containing recording state (e.g., isRecording, recordedHotkey) and control functions (e.g., startRecording).

### Example
```tsx
const recorder = useHotkeyRecorder({
  onRecord: (hotkey) => setShortcut(hotkey),
  onCancel: () => console.log('Recording cancelled'),
});
```
```

--------------------------------

### Define Hotkey Shortcuts

Source: https://tanstack.com/hotkeys/latest/docs/reference/type-aliases/Hotkey.md

Examples of defining cross-platform and platform-specific hotkeys using the Hotkey type.

```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
```

--------------------------------

### new HeldKeyCodesController(host)

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HeldKeyCodesController

Initializes a new instance of the controller and attaches it to the provided Lit component host.

```APIDOC
## constructor(host)

### Description
Creates a new HeldKeyCodesController instance to track key states for a specific Lit component.

### Parameters
- **host** (ReactiveControllerHost) - Required - The Lit component that owns this controller.
```

--------------------------------

### Parsing a KeyboardEvent

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/parseKeyboardEvent

Usage example showing how to parse a keydown event within an event listener.

```ts
document.addEventListener('keydown', (event) => {
  const parsed = parseKeyboardEvent(event)
  console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }
})
```

--------------------------------

### HotkeyRecorderController Constructor

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HotkeyRecorderController

Initialize the controller with the host component and configuration options.

```ts
new HotkeyRecorderController(_host, _options): HotkeyRecorderController;
```

--------------------------------

### Implement Konami code

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/guides/sequences.md

A sequence example requiring a specific pattern of keys within a timeout.

```typescript
useHotkeySequence(
  ['ArrowUp', 'ArrowUp', 'ArrowDown', 'ArrowDown', 'B', 'A'],
  () => enableEasterEgg(),
  { timeout: 2000 },
)
```

--------------------------------

### Implement modifier key indicators

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/reference/functions/useKeyHold

Example demonstrating tracking multiple modifier keys simultaneously.

```tsx
function ModifierIndicators() {
  const ctrl = useKeyHold('Control')
  const shift = useKeyHold('Shift')
  const alt = useKeyHold('Alt')

  return (
    <div>
      <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
      <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
      <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
    </div>
  )
}
```

--------------------------------

### new HeldKeysController(host)

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/classes/HeldKeysController

Initializes a new instance of the HeldKeysController, attaching it to a Lit component host.

```APIDOC
## Constructor

### Signature
`new HeldKeysController(host: ReactiveControllerHost): HeldKeysController`

### Description
Creates a new controller instance that tracks keyboard state for the provided Lit component host.

### Parameters
- **host** (ReactiveControllerHost) - Required - The Lit component instance that will host this controller.
```

--------------------------------

### Using hotkey() in a LitElement

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/reference/functions/hotkey

Example of applying the hotkey decorator to methods within a LitElement class.

```ts
class MyElement extends LitElement {
  @hotkey('Mod+S')
  save() { this.doSave() }

  @hotkey('Escape')
  close() { this.dismiss() }
}
```

--------------------------------

### Register multiple hotkeys

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/quick-start.md

Register several independent hotkeys within a single component setup.

```vue
<script setup lang="ts">
import { useHotkey } from '@tanstack/vue-hotkeys'

useHotkey('Mod+S', () => save())
useHotkey('Mod+Z', () => undo())
useHotkey('Mod+Shift+Z', () => redo())
useHotkey('Mod+F', () => openSearch())
useHotkey('Escape', () => closeDialog())
</script>
```

--------------------------------

### Resolving Modifiers with resolveModifier

Source: https://tanstack.com/hotkeys/latest/docs/reference/functions/resolveModifier

Examples showing how 'Mod' resolves to platform-specific keys while other modifiers remain unchanged.

```ts
resolveModifier('Mod', 'mac') // 'Meta'
resolveModifier('Mod', 'windows') // 'Control'
resolveModifier('Control', 'mac') // 'Control' (unchanged)
```

--------------------------------

### Building a Shortcut Settings UI with Lit

Source: https://tanstack.com/hotkeys/latest/docs/framework/lit/guides/hotkey-recording.md

A complete implementation of a shortcut customization panel using HotkeyRecorderController to capture new inputs and HotkeyController to manage active shortcuts.

```ts
import { LitElement, html } from 'lit'
import { customElement, state } from 'lit/decorators.js'
import {
  HotkeyRecorderController,
  HotkeyController,
  formatForDisplay,
} from '@tanstack/lit-hotkeys'
import type { Hotkey } from '@tanstack/lit-hotkeys'

interface ShortcutMap {
  save: Hotkey
  undo: Hotkey
  search: Hotkey
}

@customElement('shortcut-settings')
class ShortcutSettings extends LitElement {
  @state() private shortcuts: ShortcutMap = {
    save: 'Mod+S',
    undo: 'Mod+Z',
    search: 'Mod+K',
  }

  @state() private editingAction: keyof ShortcutMap | null = null

  private recorder = new HotkeyRecorderController(this, {
    onRecord: (hotkey) => {
      if (this.editingAction) {
        this.shortcuts = { ...this.shortcuts, [this.editingAction]: hotkey }
        this.editingAction = null
      }
    },
    onCancel: () => {
      this.editingAction = null
    },
  })

  private saveCtrl?: HotkeyController
  private undoCtrl?: HotkeyController
  private searchCtrl?: HotkeyController

  connectedCallback() {
    super.connectedCallback()
    this._registerHotkeys()
  }

  updated() {
    this._unregisterHotkeys()
    this._registerHotkeys()
  }

  private _registerHotkeys() {
    this.saveCtrl = new HotkeyController(this, this.shortcuts.save, () => save())
    this.undoCtrl = new HotkeyController(this, this.shortcuts.undo, () => undo())
    this.searchCtrl = new HotkeyController(this, this.shortcuts.search, () => openSearch())
  }

  private _unregisterHotkeys() {
    this.saveCtrl?.hostDisconnected()
    this.undoCtrl?.hostDisconnected()
    this.searchCtrl?.hostDisconnected()
  }

  disconnectedCallback() {
    super.disconnectedCallback()
    this._unregisterHotkeys()
  }

  render() {
    return html`
      <div>
        <h2>Keyboard Shortcuts</h2>
        ${(Object.entries(this.shortcuts) as Array<[keyof ShortcutMap, Hotkey]>).map(
          ([action, hotkey]) => html`
            <div>
              <span>${action}</span>
              <button
                @click=${() => {
                  this.editingAction = action
                  this.recorder.startRecording()
                }}
              >
                ${this.editingAction === action && this.recorder.isRecording
                  ? 'Press keys...'
                  : formatForDisplay(hotkey)}
              </button>
            </div>
          `,
        )}
      </div>
    `
  }
}
```

--------------------------------

### Implement a basic hotkey sequence recorder

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/guides/sequence-recording.md

Use useHotkeySequenceRecorder to manage recording state and handle sequence commits.

```vue
import { useHotkeySequenceRecorder, formatForDisplay } from '@tanstack/vue-hotkeys'
import type { HotkeySequence } from '@tanstack/vue-hotkeys'

function HotkeySequenceRecorder() {
  const recorder = useHotkeySequenceRecorder({
    onRecord: (sequence: HotkeySequence) => {
      console.log('Recorded:', sequence)
    },
  })

  return (
    <div>
      <button
        type="button"
        onClick={
          recorder.isRecording ? recorder.cancelRecording : recorder.startRecording
        }
      >
        {recorder.isRecording
          ? 'Press chords, then Enter…'
          : recorder.recordedSequence
            ? recorder.recordedSequence.map((h) => formatForDisplay(h)).join(' ')
            : 'Click to record'}
      </button>
      {recorder.isRecording && (
        <button type="button" onClick={recorder.cancelRecording}>
          Cancel
        </button>
      )}
    </div>
  )
}
```

--------------------------------

### Implement basic hotkey recording

Source: https://tanstack.com/hotkeys/latest/docs/framework/vue/guides/hotkey-recording.md

Use the useHotkeyRecorder composable to manage recording state and capture user input.

```vue
<script setup lang="ts">
import { formatForDisplay, useHotkeyRecorder } from '@tanstack/vue-hotkeys'

const recorder = useHotkeyRecorder({
  onRecord: (hotkey) => {
    console.log('Recorded:', hotkey)
  },
})
</script>

<template>
  <div>
    <button @click="recorder.isRecording ? recorder.stopRecording() : recorder.startRecording()">
      {{
        recorder.isRecording
          ? 'Press a key combination...'
          : recorder.recordedHotkey
            ? formatForDisplay(recorder.recordedHotkey)
            : 'Click to record'
      }}
    </button>
    <button v-if="recorder.isRecording" @click="recorder.cancelRecording()">
      Cancel
    </button>
  </div>
</template>
```

--------------------------------

### Access standard modifier labels

Source: https://tanstack.com/hotkeys/latest/docs/reference/variables/WINDOWS_MODIFIER_LABELS.md

Example usage showing how modifier keys map to their respective text labels.

```ts
STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
```

--------------------------------

### Implement a Shortcut Customization Panel

Source: https://tanstack.com/hotkeys/latest/docs/framework/preact/guides/hotkey-recording.md

Uses useHotkeyRecorder to capture new key combinations and useHotkey to register them for specific actions.

```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<Record<string, Hotkey>>({
    save: 'Mod+S',
    undo: 'Mod+Z',
    search: 'Mod+K',
  })

  const [editingAction, setEditingAction] = useState<string | null>(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 (
    <div>
      <h2>Keyboard Shortcuts</h2>
      {Object.entries(shortcuts).map(([action, hotkey]) => (
        <div key={action}>
          <span>{action}</span>
          <button
            onClick={() => {
              setEditingAction(action)
              recorder.startRecording()
            }}
          >
            {editingAction === action && recorder.isRecording
              ? 'Press keys...'
              : formatForDisplay(hotkey)}
          </button>
        </div>
      ))}
    </div>
  )
}
```

--------------------------------

### Basic Hotkey Recorder Implementation

Source: https://tanstack.com/hotkeys/latest/docs/framework/svelte/guides/hotkey-recording.md

A standard implementation showing how to trigger recording and display the captured hotkey in a Svelte component.

```svelte
<script lang="ts">
  import {
    createHotkeyRecorder,
    formatForDisplay,
  } from '@tanstack/svelte-hotkeys'

  const recorder = createHotkeyRecorder({
    onRecord: (hotkey) => {
      console.log('Recorded:', hotkey)
    },
  })
</script>

<div>
  <button onclick={recorder.startRecording}>
    {recorder.isRecording
      ? 'Press a key combination...'
      : recorder.recordedHotkey
        ? formatForDisplay(recorder.recordedHotkey)
        : 'Click to record'}
  </button>
  {#if recorder.isRecording}
    <button onclick={() => recorder.cancelRecording()}>Cancel</button>
  {/if}
</div>
```
Tokens:
Raw