KeyboardEvent Key Normalizer

Common errors

• TypeScript error: Cannot find name 'keyboardKey'.

  cause Attempting to use `keyboardKey` as a default import or global variable when `keyboard-key` primarily exports named functions.
  fix Use named imports for TypeScript: `import { getKey, getCode, Escape } from 'keyboard-key';`

• ReferenceError: keyboardKey is not defined

  cause Attempting to use `keyboardKey` as a global variable or accessing its members without proper ES module named imports or CommonJS destructuring.
  fix For ESM, use named imports: `import { getKey } from 'keyboard-key';`. For CommonJS, use destructuring: `const { getKey } = require('keyboard-key');`

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• deprecated 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.
  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.

Install

• npm install keyboard-key npm
• yarn add keyboard-key yarn
• pnpm add keyboard-key pnpm

Imports

• getKey
  wrong:

  import keyboardKey from 'keyboard-key'; keyboardKey.getKey(event);

  correct:

  import { getKey } from 'keyboard-key'

  `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.
• getCode
  wrong:

  const code = keyboardKey.getCode(event);

  correct:

  import { getCode } from 'keyboard-key'

  `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.
• Escape
  wrong:

  import { escape } from 'keyboard-key'

  correct:

  import { Escape } from 'keyboard-key'

  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()`.

Quickstart

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.

import { getKey, getCode, Escape } from 'keyboard-key';

document.addEventListener('keydown', (event: KeyboardEvent) => {
  const key: string = getKey(event);
  const code: number = getCode(event);

  console.log(`Key pressed: ${key}, Code: ${code}`);

  switch (key) {
    case 'Escape':
      console.log('Escape key detected via getKey!');
      break;
    case 'Enter':
      console.log('Enter key detected via getKey!');
      break;
    default:
      break;
  }

  // Using getCode with named constant
  if (code === Escape) {
    console.log('Escape key detected via getCode and constant!');
  }
});

// Simulate keydown events for demonstration purposes in a browser-like environment.
// In a real application, these would come from user interaction.
setTimeout(() => {
  const escapeEvent = new KeyboardEvent('keydown', { key: 'Escape', keyCode: 27, which: 27 });
  document.dispatchEvent(escapeEvent);
}, 100);

setTimeout(() => {
  const enterEvent = new KeyboardEvent('keydown', { key: 'Enter', keyCode: 13, which: 13 });
  document.dispatchEvent(enterEvent);
}, 200);