useRawKeyEvent

Observe every keyboard event that reaches the input chain, including key releases and modifier-only events. Prefer useHotkey for commands and useTextInput for text; this hook is for protocol-level state such as held-key tracking.

Import

import { useRawKeyEvent } from "silvery"

Usage

function HeldKeyTracker() {
  useRawKeyEvent(({ input, key }) => {
    if (key.eventType === "release") {
      releaseKey(input)
    } else if (key.isModifierOnly) {
      updateHeldModifiers(key)
    }
  })

  return null
}

Release and modifier-only events require a terminal protocol that reports them, such as Kitty keyboard protocol with the relevant flags. Legacy terminals cannot supply information they do not encode.

Signature

useRawKeyEvent(
  handler: (event: { input: string; key: Key }) => void,
  options?: { isActive?: boolean },
): void

The handler observes input; it does not consume an event or exit the runtime. Set isActive: false to keep the hook mounted without registering the observer.