@cutting/react-typed-mousetrap NPM

react-typed-mousetrap

React component that wraps use-shortcuts.

Written in typescript so you can take advantage of better typesafety

install

# yarn
yarn add @cutting/react-typed-mousetrap -S

# npm
npm install @cutting/react-typed-mousetrap -S

Usage

Declare a ShortcutMap object like below of type ShorcutMap:

import { ShortcutMap } from '@cutting/use-shortcuts';

export const shortcutMap: ShortcutMap = {
  MOVE_LEFT: [KeyCode.LeftArrow, 'a'],
  MOVE_RIGHT: [KeyCode.RightArrow, 'd'],
  MOVE_UP: [KeyCode.UpArrow, 'w'],
  MOVE_DOWN: [KeyCode.DownArrow, 's'],
  COMBINATION_EXAMPLE: { combination: [KeyCode.Ctrl, 'f'] },
  SEQUENCE_EXAMPLE: { sequence: ['x', 'c'] },
  SIMPLE_STRING: 'a'
};

You can pass simple strings, an array of strings or a combination element that requires more than one key to activate or a sequence of keys that relies on each key in the sequence being executed before the handler fires.

There is a KeyCode enum to help with the special keys.

Pass the map of values you want to hook up into a component:

<Shortcuts shortcutMap={shortcutMap} handler={handleMove} scoped>
  <div>
    {index + 1} ({x}, {y})
  </div>
</Shortcuts>

The Shortcuts component will call your handler function passing the name of the key as an action argument and the associate event object.

In the above example, there is the following configuration element:

{
  MOVE_LEFT: [KeyCode.LeftArrow, 'a'],

If the left arrow is pressed or the a key is pressed then your handler function will be called like this:

handler({type: 'MOVE_LEFT'}, e);

Which is handled in the above example like this:

const SHIFT = 10;

const handleMove = (action) => {
    switch (action.type) {
      case 'MOVE_LEFT':
        onMoveRequest({ x: x - SHIFT }, index);
        break;
      case 'MOVE_RIGHT':
        onMoveRequest({ x: x + SHIFT }, index);
        break;
      case 'MOVE_UP':
        onMoveRequest({ y: y - SHIFT }, index);
        break;
      case 'MOVE_DOWN':
        onMoveRequest({ y: y + SHIFT }, index);
        break;
      default:
        throw new Error('Unknown action');
    }

scoped

By default handlers will be added to the document object unless the scoped prop is passed in which case the component is wrapped in an html elemnt that receives the events.

Props

handler: the function that will receive the action and event arguments which the key sequence triggers.
shortcutMap: - the full configuration object for the application.
mapKey: (optional) the key from the shortcutMap that contains the configuration for this component, if omitted then the whole object is the map.
scoped: false by default. If false, events are added to the document object. If true, the component is wrapped in a wrapper html elment to which the events are assigned. tabIndex: The tab-index of the html element that wraps the component. -1 by default. Has no effect if scoped is false.
ScopedWrapperComponentType: The type of wrapper html element that wraps components when the scope prop is true. Default is <div />. Has no effect if scoped is false.