Feature Request: add options.capture

[magicdawn]

Backgroud

element.addEventListener('type', callback, { capture: true })
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture

current @tanstack/react-hotkeys simply call element.addEventListener(type, callback)
https://github.com/TanStack/hotkeys/blob/%40tanstack/vue-hotkeys%400.4.1/packages/hotkeys/src/hotkey-manager.ts#L396-L397

sometimes it matters for capture because it will trigger before any bubble stage listeners.

Feature Request

add options.capture: boolean to UseHotKeyOptions

useHotKey('Cmd+S', handleSave, { capture: true })

Other Libraries

• ahooks.useKeyPress has options.useCapture

[davidjamescarter]

+1, with a concrete case for bubble phase.

We use @tanstack/react-hotkeys alongside a docking-layout library whose tab strip handles its own keyboard navigation. Its keydown handler switches on event.key alone and doesn't check modifiers. So a Mod+Backspace meant for our app-level "close view" shortcut reaches it first and is treated as a bare Backspace. It closes the focused tab and stops propagation before our document-level listener ever sees the event. Registering in the capture phase is the only way to claim the modified keystroke first.

A proposed shape, with the default matching today's behavior:

interface HotkeyOptions {
  /** Listen in the capture phase instead of the bubble phase. @default false */
  capture?: boolean
}

One implementation detail: a single target could then have both capture-phase and bubble-phase registrations. So HotkeyManager's per-target listener and registration bookkeeping would need to be keyed by (target, phase) rather than by target alone.

We're running this as a local patch against 0.9.0. If the maintainers are open to the option, we'd be glad to open a PR with tests, docs and a changeset. (Related: #115 moves KeyStateTracker to the capture phase for a similar reason.)