{"id":11208,"library":"keyboard-key","title":"KeyboardEvent Key Normalizer","description":"`keyboard-key` is a lightweight utility library designed to provide a consistent and reliable way to determine the `KeyboardEvent.key` property from keyboard events across different browsers, addressing inconsistencies in native browser implementations. Released as version 1.1.0, this package aims to normalize keyboard event key values, stepping in where `KeyboardEvent.key` lacked full cross-browser support or where older, deprecated properties like `keyCode` and `which` were still in use. It differentiates itself by attempting to infer key values, including interpreting shift key presses, which, while helpful for `en-US` layouts, introduces a locale-specific caveat. The library also offers `getCode()` for obtaining normalized `keyCode` values and provides constants for common key codes, promoting the use of modern `KeyboardEvent.key` semantics while providing a fallback.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/levithomason/keyboard-key","tags":["javascript","typescript"],"install":[{"cmd":"npm install keyboard-key","lang":"bash","label":"npm"},{"cmd":"yarn add keyboard-key","lang":"bash","label":"yarn"},{"cmd":"pnpm add keyboard-key","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`getKey` is a named export for obtaining the normalized `key` string from a `KeyboardEvent`, which attempts to resolve cross-browser inconsistencies in the native `KeyboardEvent.key` property.","wrong":"import keyboardKey from 'keyboard-key'; keyboardKey.getKey(event);","symbol":"getKey","correct":"import { getKey } from 'keyboard-key'"},{"note":"`getCode` is a named export for retrieving a standardized `keyCode` (number) value. While `keyCode` is deprecated, this function provides a normalized value for compatibility or specific use cases.","wrong":"const code = keyboardKey.getCode(event);","symbol":"getCode","correct":"import { getCode } from 'keyboard-key'"},{"note":"Constants like `Escape` (and other key names in uppercase) are named exports, representing numeric `keyCode` values. They are useful for direct comparisons against the output of `getCode()`.","wrong":"import { escape } from 'keyboard-key'","symbol":"Escape","correct":"import { Escape } from 'keyboard-key'"}],"quickstart":{"code":"import { getKey, getCode, Escape } from 'keyboard-key';\n\ndocument.addEventListener('keydown', (event: KeyboardEvent) => {\n  const key: string = getKey(event);\n  const code: number = getCode(event);\n\n  console.log(`Key pressed: ${key}, Code: ${code}`);\n\n  switch (key) {\n    case 'Escape':\n      console.log('Escape key detected via getKey!');\n      break;\n    case 'Enter':\n      console.log('Enter key detected via getKey!');\n      break;\n    default:\n      break;\n  }\n\n  // Using getCode with named constant\n  if (code === Escape) {\n    console.log('Escape key detected via getCode and constant!');\n  }\n});\n\n// Simulate keydown events for demonstration purposes in a browser-like environment.\n// In a real application, these would come from user interaction.\nsetTimeout(() => {\n  const escapeEvent = new KeyboardEvent('keydown', { key: 'Escape', keyCode: 27, which: 27 });\n  document.dispatchEvent(escapeEvent);\n}, 100);\n\nsetTimeout(() => {\n  const enterEvent = new KeyboardEvent('keydown', { key: 'Enter', keyCode: 13, which: 13 });\n  document.dispatchEvent(enterEvent);\n}, 200);","lang":"typescript","description":"This code snippet demonstrates how to import and use `getKey()` and `getCode()` to normalize keyboard events, and how to use the provided key code constants for robust keyboard input handling."},"warnings":[{"fix":"For internationalized applications, prefer `getCode()` where consistent numeric codes are sufficient, or implement custom locale mapping logic for `key` values if string representation is critical. Thoroughly test on target locales.","message":"The `getKey()` function's logic for inferring `key` values, especially with `shift` key presses (e.g., `shift` + `/` resulting in `?`), assumes an `en-US` keyboard layout. Using different locales (e.g., German, French) will lead to incorrect `key` values for certain shifted characters or special keys.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Continue using `keyboard-key` for improved cross-browser consistency; however, ensure thorough testing across all target browser versions, especially if supporting older or less common browsers.","message":"While `keyboard-key` provides a normalized `key` property, the underlying browser support for the native `KeyboardEvent.key` has historically been inconsistent across different browsers and versions. This library aims to mitigate these inconsistencies, but developers should remain aware that edge cases might exist in very old or niche browser environments.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Prioritize `getKey()` for string representations of keys. If numeric identification is absolutely necessary for legacy compatibility or specific scenarios, use `getCode()` rather than accessing deprecated event properties directly.","message":"Direct reliance on deprecated `KeyboardEvent` properties such as `keyCode`, `charCode`, `which`, or `keyIdentifier` is highly discouraged in modern web development. While `keyboard-key` provides `getCode()` for numeric values, its primary purpose is to normalize and promote the use of the `KeyboardEvent.key` property.","severity":"deprecated","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use named imports for TypeScript: `import { getKey, getCode, Escape } from 'keyboard-key';`","cause":"Attempting to use `keyboardKey` as a default import or global variable when `keyboard-key` primarily exports named functions.","error":"TypeScript error: Cannot find name 'keyboardKey'."},{"fix":"For ESM, use named imports: `import { getKey } from 'keyboard-key';`. For CommonJS, use destructuring: `const { getKey } = require('keyboard-key');`","cause":"Attempting to use `keyboardKey` as a global variable or accessing its members without proper ES module named imports or CommonJS destructuring.","error":"ReferenceError: keyboardKey is not defined"}],"ecosystem":"npm"}