key-definitions v2.0.3

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

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

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.

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.

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).

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.

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.

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