JavaScript Keycodes: A Complete Guide to Keyboard Event Handling

The key Property: Character-Based Detection

The KeyboardEvent.key property returns the value of the key pressed by the user, taking into consideration the state of modifier keys such as Shift as well as the keyboard locale and layout.

For example, pressing the 'a' key on a QWERTY keyboard will return 'a' normally, but 'A' when Shift is held down, and entirely different characters on alternative keyboard layouts. The key property handles these variations automatically, making it the preferred choice for most text-related keyboard interactions.

This property also supports special key values like 'Enter', 'Escape', 'Tab', 'ArrowUp', and many others defined in the UI Events specification. Using key ensures your code works correctly regardless of the user's keyboard language setting or capitalization preferences.

The code Property: Physical Key Identification

The KeyboardEvent.code property represents a physical key on the keyboard, as opposed to the character generated by pressing the key. This property returns a value that isn't altered by keyboard layout or the state of modifier keys.

This makes the code property particularly valuable for gaming applications where you want consistent control mapping regardless of the user's keyboard language setting. For instance, the WASD keys for movement will always return 'KeyW', 'KeyA', 'KeyS', and 'KeyD' respectively, even on AZERTY keyboards where those physical positions produce different characters.

The code property uses string identifiers like 'KeyA', 'Digit1', 'ArrowLeft', 'Enter', 'Space', and 'Tab' that describe the physical location of the key rather than its current character output. This provides reliable, consistent key detection for gaming and keyboard shortcuts that should work identically across all keyboard layouts.

keydown Event

The keydown event fires when a key is pressed down, and it fires repeatedly if the key is held down (depending on the operating system's key repeat settings). This event fires for all keys, including function keys, modifier keys, and special keys.

The keydown event is typically used for keyboard shortcuts, game controls, and any scenario where you need to detect the initial key press regardless of whether it produces a character. When handling keydown, you can call event.preventDefault() to block default browser behavior for certain keys.

Key considerations:

• Fires immediately when any key is pressed
• Repeats during key hold (use !event.repeat to detect initial press only)
• Can prevent default browser behavior for most keys
• Fires for all keys including modifiers

keyup Event

The keyup event fires when a key is released, providing a clean signal for when a key action is complete. This event does not repeat during key hold, making it ideal for toggle actions or state management.

Common use cases:

• Releasing drag operations
• Ending text selection with Shift+Arrow keys
• Implementing keyboard shortcuts that should only trigger on key release
• Tracking key state for multi-key combinations

Using keyup for completion actions often provides a better user experience than keydown alone, as it confirms the user intentionally completed the key press.

Modifier Key Properties

The following boolean properties are available on all keyboard events:

• event.shiftKey - True if Shift was held during the key press
• event.ctrlKey - True if Ctrl was held during the key press
• event.altKey - True if Alt (Option) was held during the key press
• event.metaKey - True if Meta (Command on Mac, Windows key on Windows) was held

These properties enable complex keyboard shortcut handling without requiring separate key tracking logic. For example, detecting Ctrl+S for a save action involves checking both the key code and the modifier state simultaneously.

Performance Optimization

Keyboard event handlers should be lightweight and efficient, as they can fire hundreds of times per second during key repeats.

Optimization strategies:

• Keep handlers lightweight and avoid DOM manipulation
• Use event handlers to update state or set flags
• Perform expensive operations asynchronously
• Use requestAnimationFrame for visual updates
• Debounce rapid keyboard inputs for search operations
• Check event.repeat to ignore repeated key holds

Example debounce pattern:

let searchTimeout;
document.addEventListener('keydown', (event) => {
 if (event.target.tagName === 'INPUT') return;
 
 clearTimeout(searchTimeout);
 searchTimeout = setTimeout(() => {
 performSearch(event.key);
 }, 300);
});

Accessibility Considerations

Keyboard accessibility is essential for users who cannot use pointing devices. Ensuring your keyboard interactions are accessible benefits all users.

Essential accessibility practices:

• Visible focus indicators - Never remove focus outlines without providing alternatives
• Logical tab order - Ensure interactive elements are reachable via keyboard
• Don't trap focus - Custom interactions should not prevent navigation away
• Avoid interfering with browser shortcuts - Don't override common shortcuts
• Provide feedback - Users should receive clear feedback when actions trigger
• Test with screen readers - Ensure compatibility with assistive technology

ARIA attributes and proper semantic HTML provide the foundation for accessible keyboard interactions in web development.

Form Input Validation

Keyboard events enable real-time input validation and formatting as users type.

Common applications:

• Phone number formatting with automatic spacing
• Credit card spacing every 4 digits
• Uppercase conversion for specific fields
• Numeric-only input restriction

document.getElementById('phone').addEventListener('keydown', (e) => {
 // Allow control keys
 if (e.ctrlKey || e.altKey || e.metaKey) return;
 
 // Allow only numbers, backspace, delete, arrows
 if (!/\d/.test(e.key) && !['Backspace', 'Delete', 'ArrowLeft', 'ArrowRight'].includes(e.key)) {
 e.preventDefault();
 }
});

Note: For input value formatting, the input event is often more reliable than keyboard events alone, as it catches pastes and other input methods.

Game Controls

Games often use the code property for consistent control mapping across different keyboard layouts.

WASD movement example:

const keys = {
 KeyW: false,
 KeyA: false,
 KeyS: false,
 KeyD: false
};

document.addEventListener('keydown', (e) => {
 if (e.code in keys) {
 keys[e.code] = true;
 updatePlayerMovement();
 }
});

document.addEventListener('keyup', (e) => {
 if (e.code in keys) {
 keys[e.code] = false;
 updatePlayerMovement();
 }
});

function updatePlayerMovement() {
 const dx = (keys.KeyD ? 1 : 0) - (keys.KeyA ? 1 : 0);
 const dy = (keys.KeyS ? 1 : 0) - (keys.KeyW ? 1 : 0);
 movePlayer(dx, dy);
}

Using code values like 'KeyW' ensures the game responds to physical key positions regardless of keyboard layout.