or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-keycode

Convert between keyboard keycodes and keynames and vice versa.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/keycode@2.2.x

To install, run

npx @tessl/cli install tessl/npm-keycode@2.2.0

index.mddocs/

Keycode

Keycode is a JavaScript utility library that provides intelligent conversion between keyboard keycodes, key names, and keyboard events. It automatically detects input types and returns appropriate conversions, with comprehensive mappings for all standard keyboard keys and common aliases.

Package Information

  • Package Name: keycode
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install keycode

Core Imports

const keycode = require('keycode');

ES modules:

import keycode from 'keycode';

TypeScript:

import keycode from 'keycode';
// or with explicit typing
import * as keycode from 'keycode';

Basic Usage

const keycode = require('keycode');

// Convert from keyboard event to key name
document.addEventListener('keydown', function(e) {
  console.log('You pressed:', keycode(e)); // e.g., "enter"
});

// Convert from keycode number to key name
console.log(keycode(13)); // => "enter"

// Convert from key name to keycode number
console.log(keycode('enter')); // => 13
console.log(keycode('Enter')); // => 13 (case insensitive)

// Test if event matches specific key
document.addEventListener('keydown', function(e) {
  if (keycode.isEventKey(e, 'enter')) {
    console.log('Enter key was pressed!');
  }
});

Capabilities

Main Conversion Function

The primary keycode function intelligently detects input type and returns appropriate conversion.

/**
 * Main keycode conversion function with intelligent type detection
 * @param {Event|number|string} searchInput - Event object, numeric keycode, or key name
 * @returns {string|number|undefined} Converted value or undefined for unknown inputs
 */
function keycode(searchInput: Event): string;
function keycode(searchInput: number): string;
function keycode(searchInput: string): number;

Usage Examples:

// From keyboard event
document.addEventListener('keydown', (e) => {
  keycode(e); // => "enter", "space", "a", etc.
});

// From numeric keycode
keycode(13);    // => "enter"
keycode(32);    // => "space"
keycode(65);    // => "a"

// From key name (case insensitive)
keycode('enter');     // => 13
keycode('SPACE');     // => 32
keycode('ctrl');      // => 17
keycode('f1');        // => 112

// Single character strings
keycode('a');         // => 65
keycode('Z');         // => 90

// Unknown inputs
keycode('unknown');   // => undefined
keycode(999);         // => undefined

Event Key Testing

Compares a keyboard event against a specific key name or keycode.

/**
 * Tests if a keyboard event matches the given key name or keycode
 * @param {Event} event - Keyboard event to test
 * @param {string|number} nameOrCode - Key name or numeric keycode to compare
 * @returns {boolean} True if event matches the key, false otherwise
 */
keycode.isEventKey(event: Event, nameOrCode: string | number): boolean;

Usage Examples:

document.addEventListener('keydown', (e) => {
  // Test by key name
  if (keycode.isEventKey(e, 'enter')) {
    console.log('Enter pressed!');
  }
  
  // Test by keycode
  if (keycode.isEventKey(e, 13)) {
    console.log('Enter pressed!');
  }
  
  // Test with aliases
  if (keycode.isEventKey(e, 'ctrl') || keycode.isEventKey(e, 'control')) {
    console.log('Control key pressed!');
  }
});

Key Mappings

Access to the underlying key mapping objects for direct lookups.

/**
 * Map from key names to numeric keycodes
 */
keycode.codes: CodesMap;
keycode.code: CodesMap; // alias for codes

/**
 * Map of alternative key names to keycodes
 */
keycode.aliases: AliasesMap;

/**
 * Reverse map from numeric keycodes to key names
 */
keycode.names: InverseCodesMap;
keycode.title: InverseCodesMap; // alias for names (backward compatibility)

Usage Examples:

// Direct code lookups
console.log(keycode.codes['enter']);    // => 13
console.log(keycode.codes['space']);    // => 32
console.log(keycode.codes['f1']);       // => 112

// Direct name lookups
console.log(keycode.names[13]);         // => "enter"
console.log(keycode.names[32]);         // => "space"

// Alias lookups
console.log(keycode.aliases['ctrl']);   // => 17
console.log(keycode.aliases['esc']);    // => 27
console.log(keycode.aliases['pgup']);   // => 33

// Iterate over all codes
for (const keyName in keycode.codes) {
  console.log(keyName, '=>', keycode.codes[keyName]);
}

// Iterate over all aliases
for (const alias in keycode.aliases) {
  console.log(alias, '=>', keycode.aliases[alias]);
}

Types

interface CodesMap {
  // Control keys
  'backspace': number;
  'tab': number;
  'enter': number;
  'shift': number;
  'ctrl': number;
  'alt': number;
  'pause/break': number;
  'caps lock': number;
  'esc': number;
  'space': number;
  'page up': number;
  'page down': number;
  'end': number;
  'home': number;
  
  // Arrow keys
  'left': number;
  'up': number;
  'right': number;
  'down': number;
  
  // Edit keys
  'insert': number;
  'delete': number;
  
  // Command keys
  'command': number;
  'left command': number;
  'right command': number;
  
  // Numpad keys
  'numpad *': number;
  'numpad +': number;
  'numpad -': number;
  'numpad .': number;
  'numpad /': number;
  'numpad 0': number;
  'numpad 1': number;
  'numpad 2': number;
  'numpad 3': number;
  'numpad 4': number;
  'numpad 5': number;
  'numpad 6': number;
  'numpad 7': number;
  'numpad 8': number;
  'numpad 9': number;
  
  // Lock keys
  'num lock': number;
  'scroll lock': number;
  
  // System keys
  'my computer': number;
  'my calculator': number;
  
  // Punctuation
  ';': number;
  '=': number;
  ',': number;
  '-': number;
  '.': number;
  '/': number;
  '`': number;
  '[': number;
  '\\': number;
  ']': number;
  "'": number;
  
  // Letters (a-z)
  'a': number;
  'b': number;
  'c': number;
  'd': number;
  'e': number;
  'f': number;
  'g': number;
  'h': number;
  'i': number;
  'j': number;
  'k': number;
  'l': number;
  'm': number;
  'n': number;
  'o': number;
  'p': number;
  'q': number;
  'r': number;
  's': number;
  't': number;
  'u': number;
  'v': number;
  'w': number;
  'x': number;
  'y': number;
  'z': number;
  
  // Numbers (0-9)
  '0': number;
  '1': number;
  '2': number;
  '3': number;
  '4': number;
  '5': number;
  '6': number;
  '7': number;
  '8': number;
  '9': number;
  
  // Function keys (f1-f12)
  'f1': number;
  'f2': number;
  'f3': number;
  'f4': number;
  'f5': number;
  'f6': number;
  'f7': number;
  'f8': number;
  'f9': number;
  'f10': number;
  'f11': number;
  'f12': number;
}

interface AliasesMap {
  // System keys
  'windows': number;
  
  // Unicode symbols
  '⇧': number;  // Shift
  '⌥': number;  // Option/Alt
  '⌃': number;  // Control
  '⌘': number;  // Command
  
  // Common aliases
  'ctl': number;
  'control': number;
  'option': number;
  'pause': number;
  'break': number;
  'caps': number;
  'return': number;
  'escape': number;
  'spc': number;
  'spacebar': number;
  'pgup': number;
  'pgdn': number;
  'ins': number;
  'del': number;
  'cmd': number;
}

interface InverseCodesMap {
  [key: number]: string;
}

interface Keycode {
  (event: Event): string;
  (keycode: number): string;
  (name: string): number;
  codes: CodesMap;
  code: CodesMap; // alias for codes
  aliases: AliasesMap;
  names: InverseCodesMap;
  title: InverseCodesMap; // alias for names (backward compatibility)
  isEventKey: (event: Event, nameOrCode: number | string) => boolean;
}

Key Mappings Reference

Standard Keys

The library includes mappings for all standard keyboard keys:

  • Control keys: backspace (8), tab (9), enter (13), shift (16), ctrl (17), alt (18), etc.
  • Arrow keys: left (37), up (38), right (39), down (40)
  • Function keys: f1 (112) through f12 (123)
  • Letter keys: a (65) through z (90)
  • Number keys: 0 (48) through 9 (57)
  • Numpad keys: numpad 0 (96) through numpad 9 (105), numpad operators
  • Punctuation: All standard punctuation marks and symbols

Aliases

Common alternative names are supported:

  • Control modifiers: 'ctrl', 'ctl', 'control' → 17
  • System keys: 'cmd', 'command' → 91; 'windows' → 91
  • Navigation: 'pgup', 'pgdn' → 33, 34; 'ins', 'del' → 45, 46
  • Space variations: 'spc', 'spacebar' → 32
  • Unicode symbols: '⇧', '⌥', '⌃', '⌘' for modifier keys

Special Features

  • Case insensitive: Key name lookups work regardless of case
  • Event extraction: Automatically extracts keycodes from Event objects using which, keyCode, or charCode
  • Character codes: Single character strings return their character code
  • Error handling: Returns undefined for unknown inputs instead of throwing errors