Mousetrap

Mousetrap is a small, dependency-free JavaScript library for binding keyboard shortcuts in the browser — single keys, modifier combinations like command+shift+k, and Gmail-style key sequences like g i or the Konami code. At roughly 2KB minified and gzipped, it has no external dependencies and has historically supported browsers back to Internet Explorer 6.

The core library handles keypress, keydown, and keyup binding with a simple Mousetrap.bind(keys, callback, event) API, and its functionality is extended through a small set of official plugins (global binding outside focused inputs, pausing/unpausing all bindings, recording key sequences, and binding from a dictionary of named shortcuts) rather than baking every feature into the core.

What You Get

• Mousetrap.bind(keys, callback, event) for registering single keys, modifier combinations, or multi-key sequences
• Support for keypress, keydown, and keyup event types on the same binding API
• Konami-code-style and Gmail-style sequence binding (e.g. g i, up up down down left right left right b a enter)
• Official plugins for global binding (shortcuts that fire even while an input is focused), pausing/unpausing all bindings, recording key sequences, and binding from a name-to-shortcut dictionary
• Zero external runtime dependencies and a small (~2KB gzipped) footprint

Common Use Cases

• Adding power-user keyboard shortcuts to web applications (e.g. Gmail-style g i navigation shortcuts)
• Implementing global application shortcuts that need to work even when a text input has focus, via the global-bind plugin
• Building customizable keyboard-shortcut settings screens by combining the bind-dictionary and record plugins to capture and label user-defined shortcuts
• Adding modal or context-specific keyboard shortcuts that can be paused/resumed via the pause plugin when a dialog opens

Under The Hood

Architecture The entire core library lives in a single ~1,058-line mousetrap.js file structured as a self-invoking function that returns a Mousetrap constructor/singleton. Internally it maintains a direct map from normalized key-combination strings to callback arrays, listens for keydown/keyup/keypress at the document level, and normalizes cross-browser key codes and modifier detection (handling historical quirks like differing keyCode values across browsers) before matching the pressed sequence against registered bindings, including multi-key sequence state tracking for combos like g i. Additional behavior — global binding, pause/resume, sequence recording, dictionary-based binding — is deliberately kept out of the core and shipped as separate plugin files under plugins/, each extending the core Mousetrap object rather than being conditionally compiled in.

Tech Stack Plain vanilla JavaScript (no TypeScript, no framework dependency), built and linted via Grunt (Gruntfile.js, including a complexity-analysis task), with mousetrap.min.js as the pre-built minified distributable checked into the repo alongside the source. Tests run via Mocha with Chai assertions and jsdom/jsdom-global to simulate a DOM environment without a real browser.

Code Quality The project has a dedicated tests/ suite run via npm test (mocha --reporter=nyan) and a Grunt complexity-analysis task, suggesting some attention to keeping the single large core file maintainable despite its age and broad legacy-browser support requirements. Being last released in 2020, the library is stable but not actively evolving; its cross-browser key-code normalization logic, while effective, reflects patterns from an era before the standardized KeyboardEvent.key API was universally available.

API Design The public API is a single global object with a small, memorable method set (bind, unbind, trigger, reset) and a string-based key-combination syntax ('command+shift+k', 'g i') that reads close to natural language, requiring no build step or configuration — just <script src="mousetrap.min.js"> or require('mousetrap') and a call to bind. This low-ceremony design is a major reason for its long-standing popularity, though the plugin-based extension model means some commonly wanted behavior (global shortcuts, pausing) requires pulling in additional files rather than being available out of the box.