JavaScript event.code vs event.key Explained

Handling keyboard events in JavaScript requires choosing between event.code and event.key, two modern properties of the KeyboardEvent interface that serve fundamentally different purposes. While event.key represents the printable character or action generated by a keystroke based on layout and modifier keys, event.code identifies the physical hardware key pressed on the keyboard regardless of the user’s language settings. Understanding this distinction is essential for accurately capturing physical key inputs in applications like games, text editors, and custom shortcut systems.

What is event.key?

The event.key property returns a string representing the value of the key pressed. It accounts for the active keyboard layout, language settings, and active modifier keys (such as Shift, Alt, or Caps Lock).

For example: - Pressing the “a” key on a US QWERTY keyboard produces "a". - Holding Shift while pressing the same key produces "A". - Pressing the Enter key returns "Enter". - On a French AZERTY keyboard, pressing the top-left letter key produces "a".

Use event.key whenever your application needs to know the resulting character or standard navigation intent of a user’s input, such as in text fields, forms, or content editors.

What is event.code?

The event.code property returns a string that represents the physical key on the keyboard, completely ignoring the user’s layout, language, or modifier state. It maps directly to the physical position defined by the standard US keyboard layout.

For example: - Pressing the key labeled “Q” on a US QWERTY keyboard produces "KeyQ". - Pressing the exact same physical key on a French AZERTY keyboard (labeled “A”) still produces "KeyQ". - Pressing Shift along with that key still produces "KeyQ". - The spacebar always returns "Space".

Use event.code when the physical location of the key matters more than the character printed on the screen.

Key Differences

How to Detect Physical Key Inputs in JavaScript

To detect physical key inputs reliably across all devices and international keyboard layouts, always listen for event.code inside your event listeners.

Implementation Example: Positional Game Controls

In gaming, the standard movement cluster uses the physical “W”, “A”, “S”, and “D” keys. If you use event.key, an AZERTY user would have to reach across the keyboard to find “W” and “A”. Using event.code ensures the physical cluster works identically on all layouts:

window.addEventListener('keydown', (event) => {
  switch (event.code) {
    case 'KeyW':
      // Move forward
      break;
    case 'KeyA':
      // Move left
      break;
    case 'KeyS':
      // Move backward
      break;
    case 'KeyD':
      // Move right
      break;
    case 'Space':
      // Jump
      break;
  }
});

Best Practices

1. Use event.code for spatial interactions: Video game controls, hardware emulators, and ergonomics-based shortcuts should always rely on event.code.
2. Use event.key for character and command handling: Form validation, search bars, and universal shortcuts (like Ctrl + S or Escape) should rely on event.key.
3. Avoid deprecated properties: Do not use keyCode, which, or charCode in modern applications, as they are non-standard, inconsistent across browsers, and deprecated in the W3C specification.