About

Key-definitions module is made by one purpose: to have key definitions in one place. Key definitions are followed by MDN documentation and as recommended a web developers should check event.key on keyup event to detect pressed key (not a keydown event nor keyCode property). The reason for this read more in documentation.

Because there are numerous keyboard layouts this library is not 100% bulletproof.

Defined layouts follow QWERTY keyboards.

Usage

Before

const onKeyUpHandler = (event) => {
  if (event.keyCode === 65) {
    // this approach is deprecated by MDN
  }

  if (event.key === "ArrowLeft") {
    // check if pressed key is arrow left
  }

  if (event.key === " ") {
    // check if the key represents space
  }

  if (event.key === "A" || event.key === "B" || event.key === "C") {
    // check if event key is one of the
  }
};

useEffect(() => {
  document.addEventListener("keyup", onKeyUpHandler);

  return () => {
    document.removeEventListener("keyup", onKeyUpHandler);
  };
}, []);

Now

With new approach you can easily:

• forward event instance to compare function
• read a code easily by not memorizing what ASCII number means

import { UpperCase, ARROW_LEFT, SPACE } from "key-definitions";

const onKeyUpHandler = (event) => {
  if (compare(event, ARROW_LEFT)) {
    // you can check if given event represents space
  }

  if (event.key === ARROW_LEFT.key) {
    // you can check value by _key_ property
  }

  if (compare(event, [UpperCase.A, UpperCase.B, UpperCase.C])) {
    // check if any character is matching with event key
  }
};

useEffect(() => {
  document.addEventListener("keyup", onKeyUpHandler);

  return () => {
    document.removeEventListener("keyup", onKeyUpHandler);
  };
}, []);

Install

npm install key-definitions

or

yarn add key-definitions

Interfaces

Each key inherits KeyInterface that has following structure:

interface KeyInterface {
  keyCode: number | number[]; // event.keyCode, it can be an array in case when numerous supports for different operation systems exists
  keyCodeDefinitions?: KeyCodeSupportOS[]; // description of keyCode in case if multiple keyCode values exists
  hex?: hexNumber | hexNumber[]; // key's hex number, it's array if multiple keyCodeDefinitions exists
  code: string; // the same as event.code
  key: string; // the same as event.key
  isAltKey?: boolean;
  isMetaKey?: boolean;
  isShiftKey?: boolean;
  isCtrlKey?: boolean;
}

Functions

| Name | Description | Return value | | ----------- | -------------------------------------------------------------------------------------------------------- | ------------ | | isCharacter | Detect if pressed value is a character a-z and A-Z. | boolean | | compare | compare two values; compares key property and code in case of SHIFT, ALT and CONTROL keyboard events | boolean |

compare (value: KeyboardEvent, equalToValue: KeyInterface)

Compare event with key definitions from library.

import { SPACE } from "key-definitions";

const onKeyUp = (e: KeyboardEvent) => {
  compare(event, SPACE); // true
};

compare (value: KeyboardEvent, equalToValue: KeyInterface[])

Compare does event is one of the several key definitions from library.

import { SPACE, TAB } from "key-definitions";

const onKeyUp = (e: KeyboardEvent) => {
  compare(e.key, [SPACE, TAB]); // true
};

isCharacter (x: KeyboardEvent)

Function will check key, code or keyCode values of KeyboardEvent.

const onKeyUp = (e: KeyboardEvent) => {
  isCharacter(e); // you can forward KeyboardEvent to detect if pressed key is a character
};

document.addEventListener("keyup", onKeyUp);

isCharacter(x: string) => boolean

isCharacter("A"); // true
isCharacter("a"); // true
isCharacter("?"); // false
isCharacter("č"); // true
isCharacter("1"); // false
isCharacter("KeyA"); // true
isCharacter("KeyZ"); // true
isCharacter("Enter"); // false

isCharacter(x: number)

Even keyCode is deprecated it's still in usage by some developers. Forward keyCode value from keyup event.

isCharacter(64); // check 'a' value --> true
isCharacter(90); // check 'Z' value --> true
isCharacter(191); // check '?' value --> false
isCharacter(49); // check '1' value --> false

Supported table

Language layouts

| Language | Layout | FileName | | -------- | ------ | ---------- | | English | US | - | | Croatian | CRO | Layout_CRO | | German | DE | Layout_DE |

By default US layout is set, for different layout you need to import it independently.

import { LowerCase }, Layout_CRO, Layout_DE from "key-definitions";

console.log(LowerCase.A.key); // --> returns US layout --> value 'a'
console.log(Layout_CRO.LowerCase.A.key); // --> returns croatian layout --> value 'a'
console.log(Layout_CRO.LowerCase.Č.key); // --> returns croatian layout --> value 'č'
console.log(LowerCase.Č.key); // --> undefined (not supported for US layout)
console.log(Layout_DE.LowerCase.Ü.key); // --> returns german layout ---> value 'ü'
console.log(Layout_DE.LowerCase.UMLAUT_U.key); // --> returns german layout ---> value 'ü'

Sections

Alpha

Includes lower and upper case a-zA-Z.

| Key | Layout | | --------------- | ------ | | A-Z | all | | Č | cro | | Ć | cro | | Ž | cro | | Đ | cro | | Š | cro | | Ü (or UMLAUT_U) | de | | Ö (or UMLAUT_O) | de | | Ä (or UMLAUT_A) | de | | ẞ (or UMLAUT_S) | de |

import { LowerCase, UpperCase } from "key-definitions";

console.log(LowerCase.A.key); // --> returns value 'a'
console.log(UpperCase.A.key); // --> returns value 'A'

Digits

Includes all numerical keys 0-9 in alphanumeric keyboard section.

| Key | Name | | --- | ----- | | 0 | ZERO | | 1 | ONE | | 2 | TWO | | 3 | THREE | | 4 | FOUR | | 5 | FIVE | | 6 | SIX | | 7 | SEVEN | | 8 | EIGHT | | 9 | NINE |

import { ZERO, SEVEN } from "key-definitions";

console.log(ZERO.key); // returns value '0'
console.log(SEVEN.key); // returns value '7'

Numpad

Includes all keys in numpad section - digits and general (functional keys such as enter, num lock). Example: 0-9, NumLock, Enter; We have two sections General (functional keys) and Digits (0-9 numbers).

| Key | Name | | -------------- | ----------- | | 0-9 | ZERO-NINE | | = (equal sign) | EQUAL | | enter | ENTER | | arrow up | ARROW_UP | | arrow down | ARROW_DOWN | | arrow right | ARROW_RIGHT | | arrow left | ARROW_LEFT | | * | MULTIPLY | | + | ADD | | - | SUBSTRACT | | , | COMMA | | / | DIVIDE | | . | DECIMAL | | insert | INSERT | | end | END | | page down | PAGE_DOWN | | home | HOME | | page up | PAGE_UP | | delete | DELETE |

import { Numpad } from "key-definitions";

console.log(Numpad.ARROW_DOWN.key); // returns value 'ArrowDown'
console.log(Numpad.ZERO.key); // returns '0'

Functions

Includes all keys from F1-F12 in function section.

import { F1 } from "key-definitions";

console.log(F1.key); // returns value 'F1'

Generics

Includes functional keys in alphanumeric keyboard section. Example: AltLeft, Shift, Enter, Tab, CapsLock.

| Key | Name | | ------------ | ------------ | | tab | TAB | | enter | ENTER | | shift left | SHIFT_LEFT | | shift right | SHIFT RIGHT | | ctrl left | CTRL_LEFT | | ctrl right | CTRL_RIGHT | | alt left | ALT_LEFT | | alt right | ALT_RIGHT | | caps lock | CAPS_LOCK | | escape | ESC | | space | SPACE | | page up | PAGE_UP | | page down | PAGE_DOWN | | end | END | | home | HOME | | arrow left | ARROW_LEFT | | arrow up | ARROW_UP | | arrow right | ARROW_RIGHT | | arrow down | ARROW_DOWN | | print screen | PRINT_SCREEN | | insert | INSERT | | delete | DELETE | | num lock | NUM_LOCK | | scroll lock | SCROLL_LOCK | | help | HELP | | pause | PAUSE |

import { ALT_LEFT, ALT_RIGHT } from "key-definitions";

console.log(ALT_LEFT.key); // returns value 'Alt'
console.log(ALT_LEFT.code); // returns value 'AltLeft'
console.log(ALT_RIGHT.key); // returns 'Alt'
console.log(ALT_RIGHT.code); // returns 'AltRight'

Specials

Includes special keys like question marks )!?.$&%/#"\*) as part of alphanumeric keyboard section.

| Key | Name | | --- | -------------------- | | ! | EXCLAMATION_MARK | | " | QUOTATION_MARK | | # | HASH | | $ | DOLLAR_SIGN | | % | PERCENT | | & | AMPERSAND | | ' | APOSTROPHE | | ( | OPEN_PARENTHESIS | | ) | CLOSE_PARENTHESIS | | * | ASTERISK | | + | PLUS | | , | COMMA | | - | DASH | | . | DOT | | / | SLASH | | : | COLON | | ; | SEMICOLON | | < | LESS_THAN_BRACKET | | = | EQUAL | | > | GREATER_THAN_BRACKET | | ? | QUESTION_MARK | | @ | AMPERSAT | | [ | OPEN_BRACKET | | \ | BACKSLASH | | ] | CLOSE_BRACKET | | ^ | CARET | | _ | UNDERSCORE | | ` | BACKQUOTE | | { | OPEN_BRACE | | | | VERTICAL_BAR | | } | CLOSE_BRACE | | ~ | TILDA |

import { DOLLAR_SIGN } from "key-definitions";

console.log(DOLLAR_SIGN.key); // returns value '$'

Other resources:

https://keycode.info/for/!

https://www.computerhope.com/jargon/s/specchar.htm

https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code

https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode