Hotkeys

Hotkeys let players trigger actions directly from the keyboard, such as quick saving, skipping dialogue, or controlling a minigame. Rather than managing window.addEventListener("keydown", ...) calls yourself, it is recommended to use TanStack Hotkeys, a library that turns keyboard input into a typed command system with scopes, sequences, held keys, and conflict detection.

使用方法

Register a hotkey with the useHotkey hook:

import { useHotkey } from "@tanstack/react-hotkeys";

useHotkey("Mod+S", () => {
    quickSave();
});

The Mod modifier automatically resolves to Meta (Cmd) on macOS and Control on Windows/Linux, so the same code works across platforms.

Scoping and enabling conditionally

useHotkey is a hook, so it registers the shortcut when the component mounts and cleans it up automatically when the component unmounts — you don't need to remove the listener yourself, unlike a manual window.addEventListener.

Use the target option to limit a hotkey to a specific element, and enabled to turn it on or off based on your game state, for example while a minigame is running:

const panelRef = useRef<HTMLDivElement>(null);

useHotkey("Escape", () => closePanel(), { target: panelRef });
useHotkey("ArrowUp", () => setDirection(0, -1), { enabled: !gameOver });

Learn more

TanStack Hotkeys also supports key sequences (e.g. "G then D"), held keys, conflict detection, and a devtools panel. See the official documentation for the full feature set.