Types

Core types

Modifiers

interface Modifiers {
  ctrl: boolean;
  shift: boolean;
  meta: boolean;
  alt: boolean;
}

SafeKey

Keys that are safe to use across keyboard layouts: a–z and 0–9.

type SafeKey = "a" | "b" | ... | "z" | "0" | "1" | ... | "9";

Shortcut

A single chord: one non-modifier key plus zero or more modifiers.

interface Shortcut extends Modifiers {
  key: SafeKey;
}

ShortcutSequence

A sequence of one or more chords. "ctrl+k ctrl+c" parses to a sequence of length 2.

type ShortcutSequence = Shortcut[];

ShortcutHandler

type ShortcutHandler = (event: KeyboardEvent) => void;

Binding types

BindingOptions

Options passed to hk.add().

interface BindingOptions {
  scope?: string; // Only fires in this scope
  preventDefault?: boolean; // Default: true
  stopPropagation?: boolean; // Default: false
  enableInInput?: boolean; // Default: false
  requireReset?: boolean; // Default: false
  crossPlatform?: boolean; // Default: true
  layer?: string; // Default: "global"
}

Binding

A resolved binding (returned by getBindings()).

interface Binding extends Omit<BindingOptions, "crossPlatform"> {
  readonly sequence: ShortcutSequence;
  readonly handler: ShortcutHandler;
}

Options types

HotkeysOptions

Options for createHotkeys().

interface HotkeysOptions {
  target?: EventTarget; // Default: document
  scope?: string; // Default: "*"
  sequenceTimeout?: number; // Default: 1000 (ms)
}

Listener types

HeldKeysListener

type HeldKeysListener = (keys: ReadonlyArray<string>) => void;

KeyHoldListener

Fires true when the key is the sole key held, false otherwise.

type KeyHoldListener = (held: boolean) => void;

LayerChangeListener

type LayerChangeListener = (layers: ReadonlyArray<string>) => void;

Recording types

RecordedShortcut

Returned by recordShortcut().

interface RecordedShortcut {
  key: string; // Raw key, lowercased
  ctrl: boolean;
  shift: boolean;
  meta: boolean;
  alt: boolean;
  mod: boolean; // Platform primary (Cmd on Mac, Ctrl elsewhere)
  mod2: boolean; // Platform secondary (Ctrl on Mac, Alt elsewhere)
  safe: boolean; // Whether the key is safe cross-layout
  unsafeReason?: string; // Explanation if unsafe
}

Devtools types

DevtoolsEvent

Discriminated union of all events emitted via the __devtools hook.

type DevtoolsEvent =
  | {
      type: "binding:fired";
      shortcut: ShortcutSequence;
      layer: string;
      scope: string | undefined;
      event: KeyboardEvent;
      timestamp: number;
    }
  | {
      type: "binding:added";
      shortcut: ShortcutSequence;
      options: BindingOptions;
      timestamp: number;
    }
  | { type: "binding:removed"; shortcut: ShortcutSequence; timestamp: number }
  | { type: "layer:change"; layers: readonly string[]; timestamp: number }
  | { type: "scope:change"; scope: string; previous: string; timestamp: number }
  | { type: "held-keys:change"; keys: readonly string[]; timestamp: number }
  | { type: "lifecycle"; action: "start" | "stop" | "destroy"; timestamp: number };

DevtoolsHook

type DevtoolsHook = (event: DevtoolsEvent) => void;