Zero-dependency browser keyboard shortcut parser, OS-aware keycap badge formatter (⌘ vs Ctrl), and browser-default conflict detector.
Built for web applications, browser IDEs, and interactive shortcut trainers like Keyboard Cheat Codes.
- Cross-Platform
ModNormalization: Write"Mod+Shift+P"once and resolve tometa+shift+pon macOS orctrl+shift+pon Windows/Linux. - Browser Conflict Detection: Automatically flags shortcuts that collide with un-interceptable browser actions (
Ctrl+W,Ctrl+T,Ctrl+N) vs. interceptable browser actions (Ctrl+P,Ctrl+S,Ctrl+K). - Keycap Badge Formatting: Convert any shortcut string into clean UI keycap arrays (
["⇧", "⌘", "P"]or["Ctrl", "Shift", "P"]). - Zero Dependencies & TypeScript Ready.
npm install hotkey-shieldimport {
normalizeShortcut,
formatKeycaps,
checkBrowserConflict,
matchesKeyboardEvent
} from "hotkey-shield";
// 1. Format OS-aware keycaps for UI badges
console.log(formatKeycaps("Mod+Shift+P", "mac")); // ["⇧", "⌘", "P"]
console.log(formatKeycaps("Mod+Shift+P", "windows")); // ["Ctrl", "Shift", "P"]
// 2. Check for browser shortcut collisions
console.log(checkBrowserConflict("Ctrl+W"));
// { hasConflict: true, severity: 'critical', reason: 'Closes the active browser tab...' }
// 3. Match DOM KeyboardEvents cleanly
window.addEventListener("keydown", (e) => {
if (matchesKeyboardEvent(e, "Mod+K", "windows")) {
e.preventDefault();
console.log("Opened command palette!");
}
});