@hyperse/tinykeys

This library registers and listens to keyboard input, executing actions when the keystrokes match a user-defined shortcut.

Usage

npm install --save @hyperse/tinykeys

Commonly used key's and code's

Keybindings will be matched against KeyboardEvent.key andKeyboardEvent.code which may have some names you don't expect.

Windows	macOS	key	code
N/A	Command / ⌘	Meta	MetaLeft / MetaRight
Alt	Option / ⌥	Alt	AltLeft / AltRight
Control	Control / ^	Control	ControlLeft / ControlRight
Shift	Shift	Shift	ShiftLeft / ShiftRight
Space	Space	N/A	Space
Enter	Return	Enter	Enter
Esc	Esc	Escape	Escape
1, 2, etc	1, 2, etc	1, 2, etc	Digit1, Digit2, etc
a, b, etc	a, b, etc	a, b, etc	KeyA, KeyB, etc
-	-	-	Minus
=	=	=	Equal
+	+	+	Equal*

Key aliases

In some instances, tinykeys will alias keys depending on the platform to simplify cross-platform keybindings on international keyboards.

AltGraph (modifier)

On Windows, on many non-US standard keyboard layouts, there is a key named Alt Gr or AltGraph in the browser, in some browsers, pressing Control+Alt will report AltGraph as being pressed instead.

Similarly on macOS, the Alt (Option) key will sometimes be reported as the AltGraph key.

Note: The purpose of the Alt Gr key is to type "Alternate Graphics" so you will often want to use the event.code (KeyS) for letters instead of event.key (S)

keybindings(window, {
  'Control+Alt+KeyS': (event) => {
    // macOS: `Control+Alt+S` or `Control+AltGraph+S`
    // Windows: `Control+Alt+S` or `Control+AltGraph+S` or `AltGraph+S`
  },
  '$mod+Alt+KeyS': (event) => {
    // macOS: `Meta+Alt+S` or `Meta+AltGraph+S`
    // Windows: `Control+Alt+S` or `Control+AltGraph+S` or `AltGraph+S`
  },
});

Keybinding Syntax

Keybindings are made up of a sequence of presses.

A press can be as simple as a single key which matches against KeyboardEvent.code and KeyboardEvent.key (case-insensitive).

// Matches `event.key`:
'd';
// Matches: `event.code`:
'KeyD';

Presses can optionally be prefixed with modifiers which match against any valid value to KeyboardEvent.getModifierState().

'Control+d';
'Meta+d';
'Shift+D';
'Alt+KeyD';
'Meta+Shift+D';

There is also a special $mod modifier that makes it easy to support cross platform keybindings:

• Mac: $mod = Meta (⌘)
• Windows/Linux: $mod = Control

'$mod+D'; // Meta/Control+D
'$mod+Shift+D'; // Meta/Control+Shift+D

Alternatively, you can use parenthesis to use case-sensitive regular expressions to match multiple keys.

'$mod+([0-9])'; // $mod+0, $mod+1, $mod+2, etc...
// equivalent regex: /^[0-9]$/

Keybinding Sequences

Keybindings can also consist of several key presses in a row:

'g i'; // i.e. "Go to Inbox"
'g a'; // i.e. "Go to Archive"
'ArrowUp ArrowUp ArrowDown ArrowDown ArrowLeft ArrowRight ArrowLeft ArrowRight B A';

Each press can optionally be prefixed with modifier keys:

'$mod+K $mod+1'; // i.e. "Toggle Level 1"
'$mod+K $mod+2'; // i.e. "Toggle Level 2"
'$mod+K $mod+3'; // i.e. "Toggle Level 3"

Each press in the sequence must be pressed within 1000ms of the last.

Additional Configuration Options

You can configure the behavior of tinykeys in a couple ways using a third options parameter.

/**
 * `useShortcuts` registers and listens to keyboard strokes and
 * performs actions for patterns that match the user defined `shortcut`.
 */
import { type Action } from '@hyperse/tinykeys';
export function useShortcuts() {
  const { actions, disabled } = useYourHooks();

  const bindingEvents = useTinykeys<Action>({
    actionTree: actions,
    onActionSelect: (action) => {
      console.log(action);
    },
  });

  useEffect(() => {
    if (disabled) return;

    const unsubscribe = bindingEvents();

    return () => {
      unsubscribe();
    };
  }, [actions, disabled]);
}

options.event

Valid values: "keydown", "keyup"

Key presses will listen to this event (default: "keydown").

Note: Do not pass "keypress", it is deprecated in browsers.

options.timeout

Keybinding sequences will wait this long between key presses before cancelling (default: 1000).

Note: Setting this value too low (i.e. 300) will be too fast for many of your users.