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

Category: Javascript | April 8, 2024
Author:RobertWHurst
Views Total:10 views
Official Page:Go to website
Last Update:April 8, 2024
License:MIT

Preview:

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

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. Bind code values instead of keys.

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

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

8. 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.5.5 (04/08/2024)

  • A small release which fixes case insensitivity for checkKey.

v1.5.5 (03/14/2024)

  • A small bugfix release.

v1.5.4 (12/20/2023)

  • Bugfixes

v1.5.0 (12/16/2023)

  • Added the ability to bind code values with the default browser bindings.

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.

You Might Be Interested In:


Leave a Reply