# Sequence Recording Guide

Use `injectHotkeySequenceRecorder` to capture a series of shortcut chords. By default, each step records its physical code: pressing G twice produces `['[KeyG]', '[KeyG]']`. Set `recordBy: 'key'` to follow logical characters instead. Pass the resulting array directly to sequence registration and format each step for display.

## Record and display a sequence

This example uses a Save button so plain Enter can be recorded as a step:

```ts
import { Component } from '@angular/core'
import { formatForDisplay, injectHotkeySequenceRecorder } from '@tanstack/angular-hotkeys'

@Component({
  standalone: true,
  template: `
    <button (click)="recorder.startRecording()">Record sequence</button>
    <p>{{ label() }}</p>
    @if (recorder.isRecording()) {
      <button (click)="recorder.commitRecording()">Save</button>
      <button (click)="recorder.cancelRecording()">Cancel</button>
    }
  `,
})
export class SequenceRecorderComponent {
  readonly recorder = injectHotkeySequenceRecorder({
    commitKeys: 'none',
    onRecord: (sequence) => console.log('Register or persist:', sequence),
    onReject: ({ message }) => console.log(message),
  })
  readonly label = () =>
    (this.recorder.isRecording() ? this.recorder.steps() : this.recorder.recordedSequence() ?? [])
      .map((step) => formatForDisplay(step)).join(' → ')
}
```

## State and controls

The recorder exposes `isRecording`, `steps`, and `recordedSequence` as signal getters. `steps` contains the current attempt; `recordedSequence` contains the last committed result. `startRecording()` begins a new session. `commitRecording()` saves a nonempty attempt, while `cancelRecording()` discards it and calls `onCancel`. `stopRecording()` resets recorder state without calling `onRecord` or `onCancel`.

## Options and keyboard behavior

- `recordBy`: `'code'` by default; `'key'` records produced logical characters.
- `commitKeys`: `'enter'` by default; plain Enter commits a nonempty sequence. `'none'` lets Enter become a step and requires manual or idle commit.
- `commitOnEnter: false`: also permits Enter as a step when `commitKeys` is `'enter'`.
- `idleTimeoutMs`: optionally commits after inactivity following a completed step. No timer runs before the first step.
- `ignoreInputs`: true by default, including shadow-root inputs. Set false to record from editable fields. Escape still cancels from an input.

Escape cancels. Unmodified Backspace/Delete removes the last step; when already empty it stops and calls only `onClear`. Modifier-only presses, automatic repeats, and IME composition do not append steps. Recorded events and their releases do not trigger application shortcuts.

Set provider defaults through `provideHotkeys({ hotkeySequenceRecorder: { ... } })`.

## Validation and conflicts

`validate(sequence, { events, parsedSequence })` runs at commit. Return true to accept, or false/a message to reject. `detectConflicts` checks live bindings and sequence prefixes, including physical/logical overlap established by the recorded events. `onReject` receives feedback; rejected steps remain editable with Backspace.

The shared options and exclusions are described in the [hotkey recording guide](./hotkey-recording.md#validation-and-conflicts). The application owns reset, persistence, and any binding being edited; clearing never calls `onRecord([])`.