@usehotkeys/core
v0.1.0
Published
Framework-agnostic keyboard shortcut engine: combos, priorities, scopes and conflict resolution.
Maintainers
Readme
@usehotkeys/core
A framework-agnostic keyboard shortcut engine for the browser. Zero dependencies.
Using React? Install
@usehotkeys/reactinstead of calling this directly. This page still explains every concept it uses.
pnpm add -E @usehotkeys/coreContents
- Quick start
- Writing combos
- Sequences
- Double tap and long press
- Options
- Scopes
- Priorities and conflicts
- Typing in inputs
- Keyboard layouts
- Reading state:
getBindings,subscribe,isPressed,trigger,formatHotkey - Recording shortcuts
- Keymap: named actions and user-customizable shortcuts
- Errors
- Recipes
- Compatibility and size
- How it works (for maintainers and the curious)
- FAQ and known limits
Quick start
import { createHotkeys } from "@usehotkeys/core";
const hotkeys = createHotkeys();
// 1. Bind. You get a function back that removes the binding.
const unbind = hotkeys.bind("mod+k", (event) => {
openCommandPalette();
});
// 2. Later, when you no longer need it:
unbind();createHotkeys()makes an independent engine. Most apps create one and share it.bind(combo, handler, options?)registers a shortcut. The handler receives theKeyboardEvent.modmeans⌘on macOS andCtrlelsewhere, so one string works for everyone.- By default the browser's own action for that key is cancelled (
preventDefault), somod+swill not open "Save page".
Nothing is attached to document until the first bind, and it is detached again when the last binding is removed. Importing or creating an engine on the server does nothing.
Writing combos
A combo is modifiers and one key joined with +. Case and order do not matter.
| You write | Meaning |
| --- | --- |
| "k" | The K key, with no modifiers |
| "mod+k" | ⌘K on Mac, Ctrl+K on Windows/Linux |
| "ctrl+shift+p" | Ctrl + Shift + P |
| "esc", "enter", "space", "tab" | Named keys |
| "up", "down", "left", "right" | Arrow keys ("arrowup" also works) |
| "f5", "pageup", "home", "delete" | Function and navigation keys |
| "?", "/", "[", "," | Punctuation, written as the character |
| "ctrl++" or "ctrl+plus" | Ctrl and the + key (a bare + is the separator) |
| "numpad1" | The numeric keypad 1 |
| "shift" | Pressing Shift on its own (modifier-only) |
| ["ctrl+s", "meta+s"] | An array: several combos, one handler |
| "g i", "mod+k mod+s" | A sequence: press g, then i |
Modifier names: ctrl/control, alt/option/opt, shift, meta/cmd/command/win/super, and mod.
Modifiers are exact by default. "ctrl+k" does not fire for Ctrl+Shift+K. Set exact: false to allow extra modifiers. For symbols such as ?, Shift is implied by the character, so "?" works without writing shift+/.
Spaces separate the steps of a sequence. The space bar is "space".
Sequences
A sequence is several steps separated by spaces. The user presses them one after another, like g then i in Gmail or Ctrl+K then Ctrl+S in VS Code.
hotkeys.bind("g i", () => goToInbox());
hotkeys.bind("g g", () => scrollToTop());
hotkeys.bind("mod+k mod+s", () => openKeyboardShortcuts());How they behave:
- Timing: the next step must come within
sequenceTimeout(default1000ms, set it increateHotkeys). After that the sequence starts over. - Any other key breaks it.
g,x,idoes not fire"g i". Modifier presses between steps (holdingCtrlfrom step to step) are fine, and a held-down key (auto-repeat) counts once. - After it fires, it starts over, so
"g g"needs two new presses each time. - Every step is a full combo, with its own modifiers. A step can also be a single modifier, which means a tap: see Double tap and long press.
- Prefix bindings wait, like Vim. If you bind both
"g"and"g g", pressinggdoes not fire"g"yet: the engine waits up tosequenceTimeoutto see whether a secondgfollows. If it does, only"g g"fires. If a different key comes, or the time runs out,"g"fires then. The wait happens only when a longer sequence starting with the same keys is bound, enabled and in an active scope; a lone"g"fires instantly. The key's default action is cancelled right away (whenpreventDefaultis on), andtrigger()never waits. - Typing in inputs:
ignoreInputs: "auto"looks at the last step, so"g i"does not fire while typing, but"mod+k mod+s"does. - Only on
keydown.{ on: "keyup" }with a sequence throwsHotkeyParseError. preventDefaultapplies to the final step. Earlier keys keep their normal behaviour.hotkeys.trigger("g i")runs it, andformatHotkey("g i")gives"G I".
Double tap and long press
Double tap is a sequence that repeats the key. There is nothing extra to learn:
hotkeys.bind("k k", openSearch); // press k twice
hotkeys.bind("shift shift", openSearch); // tap Shift twice, like "Search Everywhere" in an IDE
hotkeys.bind("shift k", doSomething); // tap Shift, then press kIn a sequence, a step that is a single modifier means a tap: press and release that modifier quickly without touching any other key.
- A tap lasts at most
tapTimeout(300 ms by default, an option ofcreateHotkeys). Holding Shift while typingAis not a tap. - Taps are spaced like the other steps of a sequence, by
sequenceTimeout. - The binding fires when the second tap is released, not when it is pressed.
- A tap step is a single modifier.
"ctrl+shift ctrl+shift"throwsHotkeyParseError. - A modifier-only combo on its own (
"shift") is not a tap: it fires when the modifier is pressed, as before. ignoreInputs: "auto"ignores Shift and Alt taps while typing in an input, butctrlandmetataps still work.
Long press is the hold option, in milliseconds:
hotkeys.bind("k", showTooltip, { hold: 600 }); // fires once k has been held for 600 ms
hotkeys.bind("shift", enterSelectMode, { hold: 400 }); // also works with modifiers- It fires once, and the handler receives the original
keydownevent. Releasing the key, or one of the combo's modifiers, before the time is up cancels it. Auto-repeat is ignored. preventDefaultis applied right when the key goes down, not after the wait.- A
holdbinding is independent of plain bindings on the same keys. A plain"k"binding still fires on press. Give long press its own combo, or accept that both fire. holdneeds a single combo andon: "keydown"; with a sequence,keyup, or a value that is not greater than 0,bindthrowsHotkeyParseError.trigger()fires aholdbinding immediately, andgetBindings()includes theholdtime.
Options
Pass them as the third argument: hotkeys.bind("mod+k", handler, { scope: "editor", priority: 10 }).
| Option | Default | What it does |
| --- | --- | --- |
| scope | "global" | Scope the binding belongs to. "*" means active in every scope. See Scopes. |
| priority | 0 | Higher wins when several bindings match. See Priorities. |
| on | "keydown" | "keydown" or "keyup". Sequences need "keydown". |
| enabled | true | false turns it off. Pass a function () => boolean to decide at event time. |
| once | false | Remove the binding after it fires once. |
| hold | none | Fire only after the combo has been held this many milliseconds (long press). See Double tap and long press. |
| repeat | false | Fire again while the key is held (OS auto-repeat). Ignored by default. |
| preventDefault | true | Cancel the browser's default action for the key. |
| stopPropagation | false | Stop the event from reaching other listeners. |
| ignoreInputs | "auto" | When to skip the binding because the user is typing. See Typing in inputs. |
| element | none | Only fire when the event happens inside this element. |
| layout | "logical" | "logical" or "physical". See Keyboard layouts. |
| exact | true | Require the modifiers to match exactly. |
| passthrough | false | Let lower-ranked bindings also run. See Conflicts. |
| label | none | Human name, for help screens (getBindings()). |
| description | none | Longer text, for help screens. |
| group | none | Category, for help screens. |
Options for createHotkeys({ ... }):
| Option | Default | What it does |
| --- | --- | --- |
| target | document | Where to listen. Pass an element or window to narrow or widen it. |
| platform | detected | "mac" or "other". Changes what mod means. Handy in tests and SSR. |
| capture | false | Listen in the capture phase (runs before handlers deeper in the page). |
| tapTimeout | 300 | Longest time a modifier can be held and still count as a tap ("shift shift"). |
| sequenceTimeout | 1000 | Milliseconds allowed between the steps of a sequence, and how long a prefix binding waits. |
| keymap | none | Named actions with default shortcuts. See Keymap. |
| overrides | none | The user's saved shortcut changes, applied on top of the keymap. |
| defaults | {} | Options applied to every bind of this engine, e.g. { ignoreInputs: false }. |
| onConflict | none | Called when a new binding conflicts with an existing one. |
| debug | false | Without onConflict, log conflicts with console.warn. |
Scopes
A scope is a named group of shortcuts that is only live while the scope is active. There is always a base scope called "global".
// These only work while the "editor" scope is active.
hotkeys.bind("mod+b", toggleBold, { scope: "editor" });
hotkeys.bind("mod+i", toggleItalic, { scope: "editor" });
// This one is always live (scope defaults to "global").
hotkeys.bind("mod+k", openPalette);
// The editor gets focus: turn its scope on.
const leaveEditor = hotkeys.pushScope("editor");
// ...editor loses focus:
leaveEditor();pushScope puts a scope on top of a stack and returns the function that removes it. Scopes below stay active unless you say otherwise.
Modals: block everything behind
hotkeys.bind("escape", closeModal, { scope: "modal" });
const closeScope = hotkeys.pushScope("modal", { inherit: false });
// Now ONLY "modal" (and "*") bindings fire. "global" shortcuts are paused.
closeScope(); // everything is backinherit: false is the difference between "a modal where j/k still scroll the page behind it" and a proper modal.
Want a shortcut that works everywhere, even inside a modal (like ? for help)? Use scope: "*".
hotkeys.getActiveScopes() returns the active names, top first, e.g. ["modal"].
Priorities and conflicts
A conflict is two bindings competing for the same keys. Instead of firing both in a random order, usehotkeys picks one:
- Higher
prioritywins. - If equal, the scope closer to the top of the stack wins.
- If equal, the most recently registered binding wins (the newest component is the one the user is looking at).
Only the winner runs. Bindings that are disabled, in an inactive scope, or skipped by ignoreInputs never compete, so they cannot block anyone.
hotkeys.bind("escape", closePopover, { priority: 20 });
hotkeys.bind("escape", closeSidebar, { priority: 10 });
// Esc closes the popover first; once it is unbound, Esc closes the sidebar.To make both run, mark the higher one passthrough: true. It fires, then the next-ranked binding fires too.
Finding accidental conflicts
Two bindings with the same combo, scope, event type and priority (and neither passthrough) are a real conflict: the winner is decided only by registration order, which is fragile. Surface them:
const hotkeys = createHotkeys({
onConflict: (conflict) => {
console.warn(`"${conflict.combo}" is bound ${conflict.bindings.length} times`, conflict.bindings);
},
});
// or simply: createHotkeys({ debug: true })
hotkeys.getConflicts(); // the same information on demand, e.g. in a testFix a conflict by giving the bindings different priorities, different scopes, or passthrough.
Typing in inputs
ignoreInputs decides whether a binding is skipped because the user is typing.
| Value | Behaviour |
| --- | --- |
| "auto" (default) | Skip inside <input> (text-like types), <textarea>, <select> and contenteditable, unless the combo has ctrl or meta. So j does not fire while typing, but mod+s does. Checkboxes, radios and buttons are not "typing" and are never skipped. |
| true | Always skip inside editable elements. |
| false | Never skip. Use it for shortcuts like escape that should work everywhere. |
| ".some-selector" | Skip when the event target is inside an element matching the selector. |
| (event) => boolean | Return true to skip. Full control. |
The check looks through open Shadow DOM, so components that wrap an <input> are handled. Events while an IME (e.g. Chinese or Japanese input) is composing text are always ignored.
Keyboard layouts
Every key press has two identities: the character it types (event.key) and the position on the board (event.code). They differ on Dvorak, Colemak, AZERTY, Cyrillic and Greek layouts.
layout: "logical"(default):"s"is whichever key types ansfor this user. Right for mnemonic shortcuts (s= save,n= new).layout: "physical":"w"is the key whereWsits on a QWERTY keyboard, whatever it types. Right for games and WASD-style navigation.
hotkeys.bind("w", moveUp, { layout: "physical" });In logical mode, letters and digits fall back to the physical key when the layout cannot produce the Latin character the combo names: Option+A on macOS (which types å), a Russian layout pressing Ctrl+S (which types ы), and Shift+1 (which types !). AltGr (reported as Ctrl+Alt on Windows) is ignored for character keys.
Reading state
getBindings(): build a shortcuts help dialog
hotkeys.bind("mod+k", openPalette, { label: "Command palette", group: "Navigation" });
hotkeys.getBindings();
// [{ id: 1, combos: ["mod+k"], label: "Command palette", group: "Navigation",
// scope: "global", priority: 0, on: "keydown", enabled: true, active: true }]active is false when the binding is disabled or its scope is not live right now.
subscribe(listener) and notify(): react to changes
const stop = hotkeys.subscribe(() => {
renderHelp(hotkeys.getBindings());
});The listener runs whenever a binding is added or removed (including once bindings firing), a scope opens or closes, or a shortcut changes. getBindings() and getShortcuts() return the same array until then, so they work directly with React's useSyncExternalStore. The arrays are read-only.
The engine cannot see what an enabled function reads. If that changes, call hotkeys.notify() so subscribers refresh active.
formatHotkey(combo): show it to the user
import { formatHotkey } from "@usehotkeys/core";
formatHotkey("mod+shift+k", { platform: "mac" }); // "⇧⌘K"
formatHotkey("mod+shift+k", { platform: "other" }); // "Ctrl+Shift+K"
formatHotkey("esc"); // "⎋" on Mac, "Esc" elsewhereplatform defaults to the user's.
isPressed(combo)
hotkeys.isPressed("shift"); // true while Shift is held
hotkeys.isPressed("a");
hotkeys.isPressed("ctrl+shift"); // true while both are held; "mod" works tooState resets when the window loses focus, the tab is hidden, or Cmd is released on macOS (browsers do not send keyup for other keys in that case), so keys never get "stuck". isPressed is already false inside a keyup handler.
isPressed is a snapshot. To react to changes, hotkeys.subscribePressed(listener) calls listener on every key press and release and returns the function that stops it. While someone is subscribed the engine keeps listening to the keyboard, even with no bindings. In React use useIsPressed.
trigger(combo)
Runs the binding that would win for combo, as if the user had pressed it. Useful for a toolbar button that should do the same as the shortcut, and for tests. It returns true if a handler ran. It needs KeyboardEvent, so it throws HotkeysEnvironmentError on a server.
button.onclick = () => hotkeys.trigger("mod+k");destroy()
Removes every binding, scope and listener. Call it when you are done with an engine you created yourself.
Recording shortcuts
For a "customize your shortcuts" screen, record() waits for the user to press a combo and gives it back as a string you can store and pass to bind.
const combo = await hotkeys.record(); // the user presses Cmd+Shift+K
// "mod+shift+k" (or null if they pressed Escape)
if (combo) {
settings.save("commandPalette", combo);
hotkeys.bind(combo, openPalette);
}| Option | Default | What it does |
| --- | --- | --- |
| onChange | none | Called while keys are pressed: "mod", then "mod+shift", then "mod+shift+k". Use it for a live preview. |
| cancelKey | "escape" | Key that cancels (resolves null) when pressed alone. Pass null to be able to record escape itself. |
| mod | true | Write the platform's main modifier as mod, so a shortcut saved on a Mac also works on Windows. false keeps meta/ctrl. |
| modifierOnly | false | Also accept just modifiers ("shift"), recorded when the user lets go of them. |
| signal | none | An AbortSignal; aborting resolves null. |
- While recording, no binding fires and the keys do not reach the page, so the user can try any combo safely. Keys the browser reserves (
Ctrl+W,Cmd+Q) still cannot be captured. - Starting a new
record()cancels the previous one (it resolvesnull). Option+Aon macOS is recorded asalt+a, andShift+/as?, using the same rules as matching, so what you record always matches when pressed again.- Without a DOM (a server) the promise rejects with
HotkeysEnvironmentError.
Keymap
So far a shortcut was written next to the code that runs it. A keymap separates the two: you name an action once, give it default keys, and the user can change the keys later without any code change.
const hotkeys = createHotkeys({
keymap: {
openPalette: { keys: "mod+k", label: "Open command palette", group: "Navigation" },
save: "mod+s",
goInbox: "g i",
},
overrides: JSON.parse(localStorage.getItem("shortcuts") ?? "{}"), // the user's saved changes
});
hotkeys.bindAction("openPalette", () => openPalette());
hotkeys.bindAction("save", save);An entry is the keys ("mod+k", ["j", "arrowdown"], a sequence), or an object with keys plus label, description and group. Bindings of the action inherit that metadata, so getBindings() can build a help screen with no extra work. bindAction takes the same options as bind.
| Method | What it does |
| --- | --- |
| bindAction(action, handler, options?) | Like bind, but the keys come from the keymap. Returns the unbind function. |
| setShortcut(action, keys) | Change an action's keys. null goes back to the default, [] removes the shortcut. Existing bindings follow the change immediately; nothing is re-registered. |
| getShortcuts() | Every action with keys, defaultKeys, customized, label, group... for a settings screen. |
| getOverrides() | Only what the user changed, { openPalette: ["mod+p"] }, ready to save. |
| subscribe(listener) | Called after any change, so a settings screen can re-render. |
Letting users change a shortcut (record, apply, save):
const combo = await hotkeys.record();
if (combo) {
hotkeys.setShortcut("openPalette", combo);
localStorage.setItem("shortcuts", JSON.stringify(hotkeys.getOverrides()));
}- Saving is yours. The library never touches storage. Pass what you saved as
overridesnext time. Saved combos usemod, so they work across platforms. - Everything is validated up front. An invalid combo in
keymap/overridesthrowsHotkeyParseErrorfromcreateHotkeys; an unknown action throwsUnknownActionErrorfrombindAction,setShortcutandoverrides. - Conflicts are still reported. If the user gives two actions the same keys,
onConflict/getConflicts()tell you (see Priorities and conflicts). - A sequence cannot be assigned to an action that is bound with
on: "keyup";setShortcutthrows and changes nothing.
Errors
All errors extend HotkeysError, so instanceof works.
| Error | When |
| --- | --- |
| HotkeyParseError | A combo is invalid: empty, "ctrl+", "k+ctrl", repeated modifier, two keys, a sequence step with several modifiers and no key, a sequence on keyup, hold with a sequence or keyup, or hold not greater than 0. It has a combo property and a message saying what is wrong. Thrown by bind and formatHotkey, so mistakes show up the first time you run the code. |
| UnknownActionError | bindAction, setShortcut or overrides named an action that is not in the keymap. It has an action property. |
| HotkeysEnvironmentError | trigger or record was called where there is no DOM (KeyboardEvent, document). |
import { HotkeyParseError } from "@usehotkeys/core";
try {
hotkeys.bind(userTypedCombo, handler);
} catch (error) {
if (error instanceof HotkeyParseError) showMessage(error.message);
}Recipes
A shortcut that works even in a text field
hotkeys.bind("escape", blurEditor, { ignoreInputs: false });Different shortcuts per OS
hotkeys.bind(["ctrl+shift+z", "meta+shift+z"], redo);Scope to one component's DOM
hotkeys.bind("delete", removeCard, { element: cardElement });Fire on key release
hotkeys.bind("space", stopRecording, { on: "keyup" });Make one-off shortcuts
hotkeys.bind("enter", confirm, { once: true });Isolated engine for a widget or a test
const hotkeys = createHotkeys({ target: widgetElement, platform: "other" });
// ...
hotkeys.destroy();Use it with any framework: create the engine once, bind when the component mounts in the browser, and call the function bind returned when it unmounts. That is all the React package does.
Compatibility and size
| | |
| --- | --- |
| Browsers | Modern evergreen browsers (the build targets ES2022, so browsers from 2021 onwards). No IE, no polyfills. |
| React (@usehotkeys/react) | React 18 and 19. CI runs the hook tests against both. |
| Other frameworks | Any. The core has no framework code: create one engine, bind when the component mounts in the browser, and call the returned function when it unmounts. |
| TypeScript | Written in strict TypeScript; types are included. |
| Module formats | ESM and CommonJS, each with matching type declarations. |
| Dependencies | None. @usehotkeys/react has react and @usehotkeys/core as peer dependencies. |
| Size | About 6.7 KB minified + gzipped for @usehotkeys/core, and about 1.4 KB for @usehotkeys/react on top of it. |
| Server | Importing the packages or creating an engine on a server does nothing: no DOM access at import time, and nothing is attached until the first bind. Handling keys only makes sense in the browser. |
How it works
For people who want to contribute or debug.
- Files (
packages/core/src):parser.tsturns"mod+k"into modifier flags plus a normalised key;matcher.tscompares that with aKeyboardEvent;hotkeys.tsowns the registry, the scope stack, the pressed-key set and dispatch;filter.tsimplementsignoreInputs;format.tsrenders combos;keys.tsholds aliases.index.tsis the only public surface. - No classes. State lives in the closure that
createHotkeysreturns (the only classes are the error types). - One listener pair. The engine registers a single
keydownandkeyupon the target and does its own matching, so adding bindings never adds DOM listeners. - Dispatch (per event): drop IME events; collect candidates that match event type, repeat rule, enabled, active scope, element, keys and
ignoreInputs; sort by priority, scope depth, then registration id; run the winner (and further ones only afterpassthrough).oncebindings are removed before their handler runs. - Sequences. The engine keeps the last few non-modifier key presses with timestamps. A binding with N steps matches when the last N presses match its steps in order; presses older than
sequenceTimeoutare dropped, and the history is cleared after a sequence fires. Single combos are just sequences of one step. - Taps and holds. The engine remembers when each modifier went down and whether another key was pressed meanwhile; releasing it quickly with nothing in between adds a
tapitem to the history, which only satisfies modifier-only steps of multi-step sequences. Aholdbinding does not fire onkeydown: it starts a timer that is cancelled by thekeyupof its key or modifiers, and runs the handler when it expires. - Recorder.
record()(inrecord.ts) adds capture-phase listeners that swallow the keys, pauses dispatch while active, and builds the combo string with the same key rules as the matcher. - Change tracking. Every change bumps a
versionand calls subscribers.getBindings()/getShortcuts()cache their result per version, which is what makes them safe foruseSyncExternalStore. - Keymap. Action bindings store the action id, not fixed keys;
setShortcutre-parses the keys of the affected entries in place, so they keep their registration order. - Lazy lifecycle. Listeners attach on the first binding and detach on the last unbind.
FAQ and known limits
Why did my shortcut not fire? Check, in order: is the combo what you think (formatHotkey it)? Is its scope active (getActiveScopes())? Is another binding outranking it (getConflicts(), or set debug: true)? Is the user typing in an input (ignoreInputs)? Did the browser or OS reserve the key (Ctrl+W, Cmd+Q, Ctrl+T cannot be intercepted by any web page)?
keyup on macOS with Cmd held. The browser does not send keyup for non-modifier keys released while Cmd is down, so { on: "keyup" } bindings combined with meta will not fire. Use keydown.
Browser only. The package never touches window or document on import, but it is meant for the browser; the server is a safe no-op.
