@y.n/keys

Generic logo created using Design.com

Author: jfconde

Convert from/to event.key and event.keyCode, with types and a few goodies. In <2KB.

API 📖

Example

import {type KeyId, keyCodeToKey, keyToKeyCode} from '@y.n/keys'

let pressedKey: KeyId

document.addEventListener('keydown', (event) => {
  console.log('Pressed keyCode: ', keyToKeyCode(event.key))
  console.log('Pressed key: ', keyCodeToKey(event.keyCode))
  pressedKey = getKey(event.key).keyId
})

keyboardEvent.keyCode is deprecated. This package supports conversion from/to it, but usage of event.key is recommended instead.

the keypress event is deprecated. You should use keydown/keyup instead. If you need to support keypress, event.keyCode values will be inconsistent with keydown/keyup. The package exports a normalizeKeyPress utility that converts the most used keyCode ASCII-like values from keypress events to the equivalent ones.

Features

• Convert between key and keyCode
• Key aliasing (keyToKeyCode('ControlRight') returns 17 - the same keyCode as Control)
• TS KeyId type, provides the union of supported key library IDs
• Helper to convert keyCode values from keypress event to keyup/keydown equivalents - 81 keys supported.
• 0 dependencies.
• ESM and CJS
• All functions have linear execution time.

Design philosophy

The possible number of values for the key property is in the thousands. There are also many inconsistent or unused keyCode values.

The goal of the package is to:

• Provide extensive support for most frequent keys and layouts
  • Multimedia, F13-F24 keys and common local keys.
• Allow to type keys
• Convert between key and keyCode values.
• Keep the code ergonomic and minimize size: build lookup tables at runtime.

Bundle size

This is not the smallest package. If bundle size is critical and you don't need to handle key, but just the legacy keyCode, take a look at @timoxley's keycode.

| Feature | @y.n/keys | keycode | | -------------------------- | ------------- | ---------------------------------------------------- | | Size (minified + gzip) | 1.7 KB | 807 B | | Supported keys | 145 | 101 | | Case insensitive matching | ✅ | ✅ | | Aliasing | ✅ | Limited* | | TS Type/enum/interface | ✅ | ✅ | | Keypress supported keys | 81 | 0 | | event.key compatibility | Yes | No |

*: Using the keycode package, you can refer to the same keyCode with different names (ctrl and control). @y.n/keys goes a bit further and uses aliases to support different key variants (for example, MetaLeft, MetaRight and Meta key values all map to keyCode 91).

Install

npm install @y.n/keys

Unpkg:

https://unpkg.com/@y.n/keys@latest

Entrypoints

• @y.n/keys: main/default import, with exported functions and types.
• @y.n/keys/data: generated raw tables. Useful in case you need to iterate through all supported keys.
• @y.n/keys/lookup: helper-only subpath (you should not need this).

Usage

import { keyToKeyCode, keyCodeToKey... } from '@y.n/keys'

event.keyCode -> event.key

Use keyCodeToKey:

import { keyCodeToKey } from '@y.n/keys'

keyCodeToKey(13);
// 'Enter'

keyCodeToKey(17);
// 'Control'

keyCodeToKey(177);
// 'MediaTrackPrevious'

keyCodeToKey(999)
// undefined

event.key -> event.keyCode

Use keyToKeyCode:

import { keyToKeyCode } from '@y.n/keys'

keyToKeyCode('enter')
// 13

keyToKeyCode('ControlLeft')
// 17

keyToKeyCode('Control')
// 17

keyToKeyCode('bAckSpACE')
// 8

keyToKeyCode('InexistentKey')
// undefined

This conversion supports the keys listed at the end of this doc (145). For unsupported values it returns undefined.

Swap event.key <> event.keyCode

If you like living on the wild side, swapKeyAndKeyCode receives the value of either property (string - key - or number - keyCode), and returns the inverse:

import { swapKeyAndKeyCode } from '@y.n/keys'

swapKeyAndKeyCode('Enter')
// 13

swapKeyAndKeyCode(13)
// 'Enter'

swapKeyAndKeyCode(swapKeyAndKeyCode('Enter'))
// 'Enter'

Multiple key values can map to the same keyCode. After swapping to it, inverting it can yield a different key. In the following example, since Control, ControlLeft and ControlRight map to the same key (17), when swapping back to key the function returns Control (the alias target).

swapKeyAndKeyCode(swapKeyAndKeyCode('ControlLeft'))
// 'Control'

Normalize keyCode from keypress events

In keypress events, the value of event.keyCode is an ASCII-like value representing the content of the key, which differs to how it behaves for keydown/keyup. Using normalizeKeyPress you can convert keyCode values coming from keypress events corresponding to letters, numbers, and many other symbols. Check the complete list at the end of the doc.

import { keyCodeToKey, normalizeKeyPress } from '@y.n/keys'

normalizeKeyPress(97) // Lowercase 'a' keypress contains this keyCode
// 65
keyCodeToKey(65) // The corrected keyCode maps to the right key
// 'a'
keyCodeToKey(97) // Keycode 97 actually corresponds to Numeric Pad 1 (NP1)
// '1'

keyCodeToKey(59) // Semicolon (;) keypress contains this keycode
// 186
keyCodeToKey(186)
// ';'

Get information about a key or keyCode

You can also retrieve a small descriptor for a given key event property, keyCode event property, or KeyId (TS type / library IDs). This returns the associated key and code, and (when relevant) the descriptor for the key this one is aliased to.

import { getKeyInfo } from '@y.n/keys'

// Using the key (case insensitive)
getKeyInfo('ScrollLOCK')
// {
//   keyId: 'ScrollLock',
//   key: 'ScrollLock',
//   keyCode: 145,
//   alias: undefined
// }

// Using the keyCode
getKeyInfo(92)
// {
//   keyId: 'ContextMenu',
//   key: 'ContextMenu',
//   keyCode: 92,
//   alias: undefined
// }

// Using a KeyId (case-sensitive)
getKeyInfo('ControlRight')
// {
//   keyId: 'ControlRight',
//   key: 'ControlRight',
//   keyCode: 17,
//   alias: { keyId: 'Control', key: 'Control', keyCode: 17 }
// }

Smaller utils

The keyToKeyId and keyCodeToKeyId functions convert a case-insensitive event.key or numeric event.keyCode into the internal ID (TS KeyId type) corresponding to it. You can then query its info by using getKeyInfo.

import { keyCodeToKeyId, getKeyInfo, keyToKeyId } from '@y.n/keys'

keyToKeyId('slash')
// 'Slash'
keyCodeToKeyId(191)
// 'Slash'
getKeyInfo('Slash')?.keyCode
// 191

You might not be interested in the unaliased keys (you don't want to distinguish Alt and AltGraph but both of them). Then you can use resolveAlias with a KeyId value.

import { resolveAlias } from '@y.n/keys'

resolveAlias('MetaRight')
// 'Meta'
resolveAlias('Meta')

List of supported keys (145)

| Constant/Key | event.key | event.keyCode | Description | | ------------------ | ------------------ | ----------------: | ----------------------------------------------------------- | | Unidentified | Unidentified | 0 | Fallback value for an unidentified key event. Aliases: IME. | | Backspace | Backspace | 8 | Backspace key. | | Tab | Tab | 9 | Tab key. | | Clear | Clear | 12 | Numpad Clear key. | | Enter | Enter | 13 | Enter key. | | Shift | Shift | 16 | Shift modifier key. | | Control | Control | 17 | Control modifier key. Aliases: ControlLeft, ControlRight. | | ControlLeft | ControlLeft | 17 | Left Control variant. | | ControlRight | ControlRight | 17 | Right Control variant. | | Alt | Alt | 18 | Alt modifier key. Aliases: AltLeft, AltGraph. | | AltLeft | AltLeft | 18 | Left Alt variant. | | Pause | Pause | 19 | Pause key. | | CapsLock | CapsLock | 20 | Caps Lock key. | | Escape | Escape | 27 | Escape key. | | Spc | ' ' | 32 | Space key. | | PageUp | PageUp | 33 | Page Up key. | | PageDown | PageDown | 34 | Page Down key. | | End | End | 35 | End key. | | Home | Home | 36 | Home key. | | ArrowLeft | ArrowLeft | 37 | Left Arrow key. | | ArrowUp | ArrowUp | 38 | Up Arrow key. | | ArrowRight | ArrowRight | 39 | Right Arrow key. | | ArrowDown | ArrowDown | 40 | Down Arrow key. | | PrintScreen | PrintScreen | 44 | Print Screen key. | | Insert | Insert | 45 | Insert key. | | Delete | Delete | 46 | Delete key. | | N0 | 0 | 48 | Number 0 key. | | N1 | 1 | 49 | Number 1 key. | | N2 | 2 | 50 | Number 2 key. | | N3 | 3 | 51 | Number 3 key. | | N4 | 4 | 52 | Number 4 key. | | N5 | 5 | 53 | Number 5 key. | | N6 | 6 | 54 | Number 6 key. | | N7 | 7 | 55 | Number 7 key. | | N8 | 8 | 56 | Number 8 key. | | N9 | 9 | 57 | Number 9 key. | | Question | ? | 63 | Question mark key. | | a | a | 65 | Letter A key. | | b | b | 66 | Letter B key. | | c | c | 67 | Letter C key. | | d | d | 68 | Letter D key. | | e | e | 69 | Letter E key. | | f | f | 70 | Letter F key. | | g | g | 71 | Letter G key. | | h | h | 72 | Letter H key. | | i | i | 73 | Letter I key. | | j | j | 74 | Letter J key. | | k | k | 75 | Letter K key. | | l | l | 76 | Letter L key. | | m | m | 77 | Letter M key. | | n | n | 78 | Letter N key. | | o | o | 79 | Letter O key. | | p | p | 80 | Letter P key. | | q | q | 81 | Letter Q key. | | r | r | 82 | Letter R key. | | s | s | 83 | Letter S key. | | t | t | 84 | Letter T key. | | u | u | 85 | Letter U key. | | v | v | 86 | Letter V key. | | w | w | 87 | Letter W key. | | x | x | 88 | Letter X key. | | y | y | 89 | Letter Y key. | | z | z | 90 | Letter Z key. | | Meta | Meta | 91 | Meta modifier key. Aliases: MetaLeft, MetaRight. | | MetaLeft | MetaLeft | 91 | Left Meta variant. | | MetaRight | MetaRight | 91 | Right Meta variant. | | ContextMenu | ContextMenu | 92 | Context Menu key. | | NP0 | 0 | 96 | Numpad 0 key. | | NP1 | 1 | 97 | Numpad 1 key. | | NP2 | 2 | 98 | Numpad 2 key. | | NP3 | 3 | 99 | Numpad 3 key. | | NP4 | 4 | 100 | Numpad 4 key. | | NP5 | 5 | 101 | Numpad 5 key. | | NP6 | 6 | 102 | Numpad 6 key. | | NP7 | 7 | 103 | Numpad 7 key. | | NP8 | 8 | 104 | Numpad 8 key. | | NP9 | 9 | 105 | Numpad 9 key. | | NPMult | * | 106 | Numpad Multiply key. | | NPPlus | + | 107 | Numpad Plus key. | | NPMinus | - | 109 | Numpad Minus key. | | NPPeriod | . | 110 | Numpad Decimal key. | | NPDivide | / | 111 | Numpad Divide key. | | F1 | F1 | 112 | Function key F1. | | F2 | F2 | 113 | Function key F2. | | F3 | F3 | 114 | Function key F3. | | F4 | F4 | 115 | Function key F4. | | F5 | F5 | 116 | Function key F5. | | F6 | F6 | 117 | Function key F6. | | F7 | F7 | 118 | Function key F7. | | F8 | F8 | 119 | Function key F8. | | F9 | F9 | 120 | Function key F9. | | F10 | F10 | 121 | Function key F10. | | F11 | F11 | 122 | Function key F11. | | F12 | F12 | 123 | Function key F12. | | F13 | F13 | 124 | Function key F13. | | F14 | F14 | 125 | Function key F14. | | F15 | F15 | 126 | Function key F15. | | F16 | F16 | 127 | Function key F16. | | F17 | F17 | 128 | Function key F17. | | F18 | F18 | 129 | Function key F18. | | F19 | F19 | 130 | Function key F19. | | F20 | F20 | 131 | Function key F20. | | F21 | F21 | 132 | Function key F21. | | F22 | F22 | 133 | Function key F22. | | F23 | F23 | 134 | Function key F23. | | F24 | F24 | 135 | Function key F24. | | NumLock | NumLock | 144 | Num Lock key. | | ScrollLock | ScrollLock | 145 | Scroll Lock key. | | BrowserBack | BrowserBack | 166 | Browser Back key. | | BrowserForward | BrowserForward | 167 | Browser Forward key. | | BrowserRefresh | BrowserRefresh | 168 | Browser Refresh key. | | BrowserStop | BrowserStop | 169 | Browser Stop key. | | BrowserSearch | BrowserSearch | 170 | Browser Search key. | | DEPlus | + | 171 | German-layout plus key. | | Pipe | | | 172 | Pipe (|) character key. | | Mute | - | 173 | Mute key. | | AudioVolumeDown | AudioVolumeDown | 174 | Audio Volume Down key. | | AudioVolumeUp | AudioVolumeUp | 175 | Audio Volume Up key. | | MediaTrackNext | MediaTrackNext | 176 | Next media track key. | | MediaTrackPrevious | MediaTrackPrevious | 177 | Previous media track key. | | MediaStop | MediaStop | 178 | Stop media playback key. | | MediaPlayPause | MediaPlayPause | 179 | Play or pause media key. | | Semi | ; | 186 | Semicolon key. | | Eq | = | 187 | Equals key. | | Comma | , | 188 | Comma key. Aliases: CC. | | CC | ç | 188 | Cedilla key used on some keyboard layouts. | | Minus | - | 189 | Minus key. | | Period | . | 190 | Period key. Aliases: BRPeriod. | | Slash | / | 191 | Slash key. Aliases: BRSlash. | | BTick | | **192** | Backtick key. Aliases: UKBTick. | | Tilde | ~ | **192** | Tilde key. | | BRSlash | / | **193** | Brazilian slash variant key. | | BRPeriod | . | **194** | Brazilian period variant key. | | LBracket | [ | **219** | Left bracket key. | | BSlash | \ | **220** | Backslash key. Aliases: INTBSlash. | | RBracket | ] | **221** | Right bracket key. | | Quote | ' | **222** | Quote / apostrophe key. | | DoubleQuote | " | **222** | Double quote key. | | UKBTick | | 223 | UK backtick variant key. | | AltGraph | AltGraph | 225 | AltGraph modifier key. | | INTBSlash | \ | 226 | International backslash variant key. | | IME | Dead | 229 | IME dead/composition key. | | HiraganaKatakana | HiraganaKatakana | 242 | Hiragana/Katakana toggle key. | | ZenkakuHankaku | ZenkakuHankaku | 243 | Zenkaku/Hankaku toggle key. | | KanjiMode | KanjiMode | 244 | Kanji mode key. |

List of available keypress codes using normalizeKeyPress (81)

| Keypress keyCode | converted keyCode | Pressed key | Description | | ---------------: | ----------------: | ----------- | ----------------------------------------------------------------------------- | | 13 | 13 (Kept) | Enter | Enter is preserved as-is (no need to convert). | | 32 | 32 (Kept) | Spacebar | Spacebar ( ) (no need to convert). | | 48-57 | 48-57 (Kept) | 0-9 | Numbers are preserved as-is (no need to convert). | | 63 | 63 (Kept) | ? | Often specific to certain older browser implementations (no need to convert). | | 65-90 | 65-90 (Kept) | A-Z | Uppercase letters are preserved as-is (no need to convert). | | 97-122 | 65-90 | a-z | Converted to equivalent uppercase key press. | | 42 | 106 | * | Numpad Multiply (*). | | 43 | 107 | + | Numpad Add (+). | | 45 | 109 | - | Numpad Subtract (-). | | 46 | 110 | . | Numpad Decimal (.). | | 47 | 111 | / | Numpad Divide (/). | | 124 | 172 | | | Pipe (|). | | 59 | 186 | ; / : | Semicolon (;). | | 61 | 187 | = / + | Equal sign (=). | | 44 | 188 | , | Comma (,) | | 231 | 188 | ç | Also mapped to Comma/188 in specific locales (like Brazilian ABNT). | | 96 | 192 | ` / ~ | Backtick / Grave accent | | 126 | 192 | ~ | Tilde (~) | | 91 | 219 | [ / { | Left Bracket ([) | | 92 | 220 | \ | Backslash (\) | | 93 | 221 | ] / } | Right Bracket (]) | | 39 | 222 | ' | Single Quote | | 34 | 222 | " | Double Quote |

License

This project is licensed under the GPL v3 license. Credit is appreciated, but feel free to do anything you want with this source.

Credits and references

• KeyboardEvent - MDN
• All Key Codes - by Toptal and Keycode tester - by Toptal
• keycode - by timoxley
• CDK - keycodes
• Several pages about specific key quirks