hyper-interactive

Events triggered on complex mouse and keyboard interactions.

Inspired by mousetrap, hyper-interactive is more flexible - It allows any key to act as a modifier, has parentheses and not operations, and allows to combine your event formulas in an almost infinite number of ways.

npm install hyper-interactive

How to use

Import HyperInteractive

import HyperInteractive from "hyper-interactive";

Wrap target element to watch for events

const hyper = new HyperInteractive();

Add interaction events

You can add events using .addInteractions() or a single event using .addInteraction().

hyper.addInteraction({
  formula: "a",
  reaction: () => alert("a key was pressed!")
});

Additionally you can check the latest event with .check()

hyper.check("space", "keydown);

Add more complicated interactions

You can get quite complex with you interaction codes, allowing you to enter sequences and combinations of keys

hyper.addInteractions([
	{
		formula: "space+b",
		reaction: () => alert("spacebar and b keys were both pressed!")
	},
	{
		formula: "[|]",
		reaction: () => alert("[ or ] key was pressed!")
	},
	{
		formula: "k o n a m i",
		reaction: () => alert("konami was typed!")
	},
	{
		formula: "esc+(k o n a m i)",
		reaction: () => alert("konami was typed whilst holding the escape key!")
	}
]);

Interaction formulas

Key Combos

Using a + symbol you can create an event when a combination of keys are pressed. This is not just limited to the standard modifier keys but can be any key combination. The following are all valid formulas.

shift+a
a+b
space+F10

Or operators

Using the | you can create an or operator. The formula a|b will trigger an event if either a or b is pressed.

Konami code

You can create an event based on a sequence of key presses using a space inbetween codes. You can even combine it with the syntax above. Try the following.

h e l l o
space+(h e l l o)
a b+c d|e f g

Brackets

You can use brackets to control the order of evaluation. For example a+(b|c|d) will check a is pressed and any of b, c, or d is pressed. (a+b)|c|d will check if a and b are pressed together or c or c are pressed on their own.

Not Operator

An ! can be used to exclude keys. !(a|b) will fire any time a key is pressed that is not a or b. You could use this in combination, a+b+!c+!d will be triggered if a and b are down but only if c and d are not.

Available Keys

You can use any KeyEvent.code value as a key, along with the following aliases, all case insensitive. A KeyEvent.keyCode fallback has been provided for older browsers.

| KeyCode | Description | | ----------- | ----------- | | * , any | Any | | shift | ShiftLeft or ShiftRight | | ctrl , control | ControlLeft or ControlRight | | alt , opt , option | AltLeft or AltRight | | meta , cmd , command | MetaLeft or MetaRight | | mod , modifier | Meta for Apple devices, Control for others | | esc , escape | Escape | | _ , space | Space | | del | Backspace or Delete | | up | ArrowUp | | down | ArrowDown | | left | ArrowLeft | | right | ArrowRight | | - | Minus | | = | Equal | | [ | BracketLeft | | ] | BracketRight | | ; | Semicolon | | ' | Quote | | \ | Backslash | | , | Comma | | . | Period | | / | Slash | | 0-9 | Digit0-Digit9 | | a-z | KeyA-KeyZ |

While we patiently wait for Keyboard.getLayoutMap() you can pass different keyboard maps via the third argument of the HyperInteractive constructor.

new HyperInteractive({target, interactions, keyboardMap, getTarget})

Additionally you can use .addKeyCodes() to create additional key codes. These can use any formula value. For example.

hyper.addKeyCodes({
    "?": "shift+/",
    "save": "mod+s"
})

Custom targets

You can use getTarget in the constructor to define custom target for events. This can allow you to select your own elements when using Canvas / WebGL.

const getTarget = event => (event.target === canvas ? getCanvasTarget() : event.target);
new HyperInteractive({target, interactions, keyboardMap, getTarget})

To do

• add mouse / pointer events
• provide additional keyboard layouts