Skip to content

Declarative React component to deal with hotkeys

License

Notifications You must be signed in to change notification settings

shelfio/hotkeys

Repository files navigation

@shelf/hotkeys

A tiny (1Kb) set of React hotkeys utilities to make great user experience 🚀. Build on top of tinykeys

Features:

  • Global hotkeys
  • Element specific hotkeys
  • Modifiers support
  • Sequence hotkeys
  • Disabled on input elements by default
  • TypeScript support
  • 100% test coverage
  • Pure ESM build. See

Installation

yarn add @shelf/hotkeys react

Usage

import {Hotkey} from '@shelf/hotkeys';

function Demo() {
  return (
    <Hotkey
      binding={'$mod+a'}
      onAction={() => {
        // Do some amazing stuff 🚀
      }}
    />
  );
}

Hotkey

binding See tinykeys for more info

onAction Function to be called when hotkey is pressed. Accept Keyboard event as first argument.

options.disableOnInputs Disable hotkey when input/textarea element is focused. Default: true

Examples:

<Hotkey binding={'a'} onAction={}/> // single key case insensitive
<Hotkey binding={'1'} onAction={}/> // number keys
<Hotkey binding={'Escape'} onAction={}/>
<Hotkey binding={'Enter'} onAction={}/>

// ⌘ + a on macOS, Ctrl + a on Windows and Linux
<Hotkey binding={'$mod+a'} onAction={}/>

// sequence hotkey support by empty space
<Hotkey binding={'g i'} onAction={}/>

// combination of keys, make sure no spaces between keys
<Hotkey binding={'Control+a'} onAction={}/>

// $mod is a special key for ⌘ on macOS and Ctrl on Windows and Linux
<Hotkey binding={'$mod+a'} onAction={}/>


// Prevent default browser action opening new tab
<Hotkey binding={'$mod+T'} onAction={event => {
  event.preventDefault();
}}/>


// Enable hotkey when input/textarea element is focused
<Hotkey
  binding={'a'}
  onAction={}
  options={{
    disableOnInputs: false,
    event: 'keyup' // default is keydown
  }}
/>

useHotkeys

useHotkeys(keymap, [options], [element]) is a hook that allows you to register multiple hotkeys at once.

import {useHotkeys} from '@shelf/hotkeys';

function Demo() {
  useHotkeys(
    {
      '$mod+a': () => {},
      'g i': () => {},
      // Do some amazing stuff 🚀
    },
    {
      disableOnInputs: false,
    }
  );

  return <div>...</div>;
}

Publish

$ git checkout master
$ yarn version
$ yarn publish
$ git push origin master --tags

License

MIT © Shelf