Bind Custom Functions To Keys And Key Combos – Keystrokes.js

Preview:

Description:

Keystrokes.js is an easy yet robust JavaScript library designed to simplify the binding of functions to keys and key combinations.

It can be seamlessly integrated with popular JS frameworks like React and Vue and also work in Node for non-UI apps.

Use Cases:

• Create keyboard shortcuts to perform actions like save, undo, redo, etc.
• Bind player actions to keyboard keys for game controls
•  Implement shortcuts for accessibility features like skip to main content, toggle high contrast mode, etc.

How to use it:

1. Install and import the Keystrokes.

# Yarn
$ yarn add @rwh/keystrokes
# NPM
$ npm i @rwh/keystrokes

import { bindKey, bindKeyCombo } from '@rwh/keystrokes'

2. Bind functions to keys or key combos by calling the bindKey()/bindKeyCombo() function. The function accepts two arguments – the key or key combo you wish to bind and the function to be executed when the specified key(s) are pressed.

bindKey('a', () =>
  console.log('You pressed "a"')
)

bindKeyCombo('ctrl > a, c', () =>
  console.log('You pressed "ctrl" then "a", released both, and are pressing "c"')
)

3. You can also pass the events in a JS object as follows:

bindKey('a', {
  onPressed: () => console.log('You pressed "a"'),
  onPressedWithRepeat: () => console.log('You\'re pressing "a"'),
  onReleased: () => console.log('You released "a"'),
})

bindKeyCombo('ctrl > c, a', {
  onPressed: () => console.log('You pressed "ctrl" then "c", released both, then pressed "a"'),
  onPressedWithRepeat: () => console.log('You pressed "ctrl" then "c", released both, and are pressing "a"'),
  onReleased: () => console.log('You released "c"'),
})

4. Unbind keys or key combos.

import { unbindKey, unbindKeyCombo } from '@rwh/keystrokes'

unbindKey('a', () =>)
unbindKeyCombo('ctrl > c, a', () =>)

5. Check keys or key combos.

import { checkKey, checkKeyCombo } from '@rwh/keystrokes'

const keyIsPressed = checkKey('a')
const keyComboIsPressed = checkKeyCombo('ctrl > c, a')

6. Set global options.

import { setGlobalKeystrokesOptions } from '@rwh/keystrokes'

setGlobalKeystrokesOptions({
  selfReleasingKeys: [],
  keyRemap: {},
  onActive: handler => {
    const listener = () => handler()
    window.addEventListener('focus', listener)
    return () => {
      window.removeEventListener('focus', listener)
    }
  },
  onInactive: handler => {
    const listener = () => handler()
    window.addEventListener('blur', listener)
    return () => {
      window.removeEventListener('blur', listener)
    }
  },
  onKeyPressed: handler => {
    const listener = event => handler({ key: event.key, originalEvent: event })
    window.addEventListener('keydown', listener)
    return () => {
      window.removeEventListener('keydown', listener)
    }
  },
  onKeyReleased: handler => {
    const listener = event => handler({ key: event.key, originalEvent: event })
    window.addEventListener('keyup', listener)
    return () => {
      window.removeEventListener('keyup', listener)
    }
  }
})

7. Create an instance of Keystrokes instead of using the global instance.

// Import
import { Keystrokes } from '@rwh/keystrokes'
// Create an instance
const keystrokes = new Keystrokes()
// API
keystrokes.bindKey(...)
keystrokes.bindKeyCombo(...)
keystrokes.unbindKey(...)
keystrokes.unbindKeyCombo(...)
keystrokes.checkKey(...)
keystrokes.checkKeyCombo(...)

Changelog:

v1.3.0 (11/08/2023)

• This release introduces the ability to bind (and unbind) more than one key or combo at the same time.

v1.2.3 (09/02/2023)

• This release features a refinement of sequence behavior. It was found that it was possible to press keys between a completed sequence.

v1.2.1 (08/19/2023)

• Bugfix

v1.2.0 (08/10/2023)

• Changed the way key combos are executed so that you can interact with events. This means that things like calling preventDefault are accounted for correctly.

v1.1.5 (08/07/2023)

• Bugfixes

v1.1.2 (07/26/2023)

• Bugfixes

v1.1.1 (07/24/2023)

• Fixes an issue with combos containing the shift key in which they would not be triggered correctly.