@quickey/binder

Subscribe to keyboard key bindings

Intro

Quickey Binder will help you to craete keyboard key combination subscriptions. Want to know when a user presses Ctrl + H? or maybe you want to create an easteregg for your web app and want to know that a user entered a combination of keys? Quickey Binder is the tool you need.

Install

Quickey Binder can be installed via npm:

$ npm install --save @quickey/binder

Or via yarn:

$ yarn add @quickey/binder

Or using the CDN:

<script src="https://unpkg.com/@quickey/binder@latest/umd/quickey.binder.js"></script>

Or the minified version:

<script src="https://unpkg.com/@quickey/binder@latest/umd/quickey.binder.min.js"></script>

Usage

import { KeyBinder } from "@quickey/binder";

// Or when using the UMD module

const { KeyBinder } = Quickey.binder;

const keyBinder = new KeyBinder();

keyBinder.delegate = {
  didMatchFound: function(binder, matches, target) {
    console.log(binder, matches, target);
  }
}

keyBinder.bind({
  keys: "I > D > D > Q > D"
});

keyBinder.bind({
  keys: "Ctrl + H"
});

keyBinder.bind({
  keys: "J"
});

For your convenience, we created this Fiddle, so you can take Quickey Binder for a quick spin.

API

KeyBinder

KeyBinder([options])

Type: constructor

Creates a new KeyBinder.

options

Type: object - optional

bindings

Type: Array

A list of combinations to bind to. See keyBindingOptions for details.

disabled

Type: boolean

Should the key binder listen or halt key bindings.

target

Type: EventTarget

KeyBinder creates a Keyboard under the hood, this is the keyboard's EventTarget.

All options are optionals

.disable()

Disables the key binder.

.enable()

Enables the key binder.

.bind([keyBindingOptions])

Subscribe to key binding.

keyBindingOptions

Type: object

id

Type: string - optional

You can supply an id to the key binding so you can remove it later if you want to.

keys

Type: string

The combination of keys to bind to.
For Combination binding (hold them together to activate) create a list of keys separated with the + sign. For example:
Ctrl + H, Ctrl + Alt + Delete, Shift + R

For Stream binding (enter one after another to activate) create a list of keys separated with the > sign. For example:
I > D > D > Q > D, Ctrl > Ctrl, H > E > L > L > O

For Single binding (enter one key) supply the key you want to bind to. For example:
J, F, K

See this list for uniqe key options.

alias

Type: Array - optional

You can supply a list of keyBindingOptions to the alias option to create aliases with this binding.

delay

Type: number

The delay between key strokes when using Stream bindings.

strict

Type: boolean

In Combination bindings, strict mode will activate only if the binded keys are the only active keys in the keyboard.
In Stream bindings, each key must be released before the next one is active.
In Single bindings, only one key must to be active.

.unbind([keyBindingId])

Unsubscribe from key binding.

keyBindingId

Type: string

.removeAll()

Unsubscribe all key bindings.

.destroy()

Unsubscribe all key bindings and destroys the Keyboard.

.disabled

Type: boolean

Get the key binder disabled state.

.delegate

Type: object

Attach a delegate to KeyBinder instance.

didMatchFound([binder,matches,target])

This function gets called each time a subscribed key binding is detected.

Type: function

binder

Type: object

The key binder instance in which the detection occurred.

matches

Type: Array

A list of key binding matches.

target

Type: EventTarget

The key binder keyboard target.

← Go back to Quickey