README

*⃣ shortkey

A small library to handle keyboard events in a more declarative way

Install
Examples
API
Browser support

Install

npm install shortkey

Examples

Both examples use the HTML dialog element. To learn more, check out this demo about the dialog element.

DOM `addEventListener()`

import shortkey from 'shortkey';

const dialog = document.createElement('dialog');

dialog.innerText = 'Dialog message';

dialog.addEventListener(
  'keydown',
  shortkey({
    onEscape: () => {
      dialog.close();
    },
  })
);

const button = document.createElement('button');

button.innerText = 'Open dialog';

button.addEventListener('click', () => dialog.showModal());

const fragment = document.createDocumentFragment();

fragment.appendChild(button);

fragment.appendChild(dialog);

document.body.appendChild(fragment);

React and ReactDOM

import React from 'react';
import ReactDOM from 'react-dom';
import shortkey from 'shortkey';

class App extends React.Component {
  constructor() {
    super();
    this.dialogRef = React.createRef();
  }

  get dialog() {
    return this.dialogRef.current;
  }

  handleButtonClick = () => this.dialog.showModal();

  handleDialogKeyDown = shortkey({
    onEscape: () => this.dialog.close(),
  });

  render() {
    return (
      <React.Fragment>
        <button onClick={this.handleButtonClick}>Open dialog</button>
        <dialog onKeyDown={this.handleDialogKeyDown} ref={this.dialogRef}>
          Dialog message
        </dialog>
      </React.Fragment>
    );
  }
}

ReactDOM.render(<App />, document.getElementById('root'));

API

Shortkey accepts a plain object. The keys are the event names. The values are the corresponding event handlers. The return value is a function.

The event names are matched against the KeyboardEvent's ctrlKey, altKey, shiftKey, metaKey and key attributes (in that order) and prefixed with 'on'.

shortkey({
  onDelete: e => console.log(e.key) /* Delete */,
  onArrowDown: e => console.log(e.key) /* ArrowDown */,
  onArrowUp: e => console.log(e.key) /* ArrowUp */,
  onShiftArrowLeft: e => console.log(e.key) /* ArrowLeft */,
  onCtrlAltDelete: e => console.log(e.key) /* Delete */,
  onShiftMetaEnter: e => console.log(e.key) /* Enter */,
});

Check the UI Events KeyboardEvent key Values spec for a list of the key attribute's possible values.

Browser support

Shortkey supports every browser that supports the KeyboardEvent's key, ctrlKey, altKey, shiftKey and metaKey attributes. MDN has a detailed overview of the KeyboardEvent's browser compatibility.

Shim

IE and Edge use non-standard KeyboardEvent.key identifiers. Depending on the key you're targetting, you might need a shim.

Note: this isn't necessary if you're using React with ReactDOM

import 'shim-keyboard-event-key';
import shortkey from 'shortkey';

const handler = shortkey({
  onEscape: e => console.log(e.key) /* Escape */,
});

Usage no npm install needed!