keyboard-interactions
Action-based hotkey management with swappable input adapters

Overview

Bind keyboard (and other input) combos to named actions. Actions can be rebound at runtime via a built-in UI dialog. The library ships as three independent packages:

Import	Contents
@nk11/keyboard-interactions	Core — action registry, mousetrap adapter
@nk11/keyboard-interactions/react	React hooks — useHotkeys, useSvelteComponent
@nk11/keyboard-interactions/ui	Svelte components — KeybindingsEditorDialog, KeyBindingsEditor, DebugLog
@nk11/keyboard-interactions/adapters/humaninput	HumanInput adapter (gamepad, touch, speech, …)
@nk11/keyboard-interactions/adapters/keypress	Keypress.js adapter

Installation

npm install @nk11/keyboard-interactions

Basic usage

import { Hotkeys } from "@nk11/keyboard-interactions";

// 1. Register actions (once, at app init)
Hotkeys.register("save", "ctrl+s", { title: "Save", description: "Save the document" });
Hotkeys.register("undo", "ctrl+z", { title: "Undo" });

// 2. Bind handlers (scoped to window by default, or any DOM element)
const hk = Hotkeys(window);

hk.on("save", (e) => save());
hk.on("undo", (e) => undo());

// 3. Unbind
hk.off("save", handler);

Scope hotkeys to a specific element:

const hk = Hotkeys(document.querySelector("#my-panel"));
hk.on("move-up", () => moveUp());

Theming

import "@nk11/keyboard-interactions/ui/index.css";

// pick one:
import "@nk11/keyboard-interactions/ui/themes/dark.css";
import "@nk11/keyboard-interactions/ui/themes/light.css";

Or define your own CSS variables — see src/gui/themes/dark.css for the full list.

Pluggable adapters

Core ships with mousetrap as the default keyboard adapter. To use an alternative, import the adapter and register it:

import { Hotkeys } from "@nk11/keyboard-interactions";
import { getHumanInputInstance } from "@nk11/keyboard-interactions/adapters/humaninput";
import { getKJSInstance } from "@nk11/keyboard-interactions/adapters/keypress";

Hotkeys.registerInputType("humaninput", getHumanInputInstance);
Hotkeys.registerInputType("keypress", getKJSInstance);

// then use the type in your combo params:
Hotkeys.register("jump", [{ type: "humaninput", combo: "space" }], { title: "Jump" });

Adapters not imported are never bundled — fully tree-shakeable.

React

npm install @nk11/keyboard-interactions react

useHotkeys — fluent hotkey binding with automatic cleanup

import { useHotkeys, HotkeysDef } from "@nk11/keyboard-interactions/react";

const keys = {
  pause:   { keys: "p", title: "Pause",   description: "Pause / unpause" },
  restart: { keys: "r", title: "Restart", description: "Restart the game" },
} satisfies HotkeysDef;

function Game() {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useHotkeys(keys, canvasRef)       // scope to element, or omit for window
    .on("pause",   () => togglePause())
    .on("restart", () => restart());

  // held keys (keydown + keyup)
  useHotkeys({ thrust: { keys: "space", title: "Thrust" } }, canvasRef)
    .on("thrust", { keydown: () => startThrust(), keyup: () => stopThrust() });

  return <canvas ref={canvasRef} />;
}

useSvelteComponent — mount Svelte 5 components in React

Use this to render the built-in UI components (KeybindingsEditorDialog, KeyBindingsEditor, DebugLog) from React:

import { useSvelteComponent } from "@nk11/keyboard-interactions/react";
import { KeybindingsEditorDialog } from "@nk11/keyboard-interactions/ui";
import "@nk11/keyboard-interactions/ui/index.css";

function App() {
  const dialogRef = useSvelteComponent(KeybindingsEditorDialog, {
    persistenceKey: "my-app-keybindings",  // optional: saves/restores from localStorage
  });

  return <div ref={dialogRef} />;
}

Press H to open the dialog. Rebind any key — bindings are saved to localStorage automatically and restored on next load. A Reset all button appears in the editor header whenever any binding differs from its default.

API

Hotkeys.register(action, combo, options?)

Param	Type
action	string — unique action name
combo	string | ComboParam | (string | ComboParam)[]
options	Partial<ActionOptions> — title, description, category, preventDefault, stopPropagation, persistent

Hotkeys(target?)

Returns a HotkeysInstance scoped to target (default: window).

• .on(action, handler, extraHandler?) — bind keydown (+ optional keyup)
• .off(action, handler) — unbind

Static methods

Method	Description
Hotkeys.register(...)	Declare an action
Hotkeys.clearRegistered()	Remove all non-persistent actions
Hotkeys.registerInputType(type, factory)	Plug in a custom adapter
Hotkeys.getRegistered()	Return all registered actions
Hotkeys.onChange(handler)	Subscribe to registry changes
Hotkeys.onAction(handler)	Subscribe to action triggers

Utilities

• rebind(action, comboIndex, newCombo) — remap a combo at runtime
• resetActionCombosToDefault(action, comboIndex?) — restore defaults
• addComboForAction(action) — append a new empty combo slot
• getActionByName(action) — look up a registered action

Credits

• mousetrap — Craig Campbell
• Keypress.js — David Mauro
• HumanInput — Dan McDougall