README.md

react-key-handler 🔑

React component to handle key events.

Table of Contents

1. Installation
2. Usage
3. keyHandler decorator
4. keyToggleHandler decorator
5. KeyHandler component
6. Form key handling
7. Demos
8. Development
9. Contributing
10. License

Installation

$ npm install react-key-handler --save

Usage

react-key-handler comes in 2 flavors, a component and decorators.

Unless you want absolute flexibility we highly recommend you to use one of the decorators.

keyHandler decorator

The decorator will decorate the given component with a keyValue, keyCode and keyName property.

import React from 'react';
import {keyHandler} from 'react-key-handler';

const S_KEY_CODE = 77;

function DecoratorDemo({keyCode}) {
  return (
    <div>
      {keyCode === S_KEY_CODE &&
        <ol>
          <li>hello</li>
          <li>world</li>
        </ol>
      }
    </div>
  );
}

export default keyHandler({keyCode: S_KEY_CODE})(DecoratorDemo);

The prop types of the keyHandler decorator are:

type Props = {
  keyValue: ?string,
  keyCode: ?number,
  keyEventName: ?string,
  keyName: ?string,
}

• keyValue can be any given W3C keyboard key value
• keyCode can be any given keyboard code
• keyEventName will default to 'keyup'
• keyName can be any given character

You should either pass a keyValue, a keyCode or a keyName, not both.

keyToggleHandler decorator

This decorator has the exact same API as the keyHandler decorator and should be used for when you're looking to toggle a key.

KeyHandler component

import React from 'react';
import KeyHandler from 'react-key-handler';

const S_KEY_CODE = 77;

export default React.createClass({
  getInitialState() {
    return {showMenu: false};
  },

  render() {
    const {showMenu} = this.state;

    return (
      <div>
        <KeyHandler keyCode={S_KEY_CODE} onKeyHandle={this.toggleMenu} />

        {showMenu &&
          <ol>
            <li>hello</li>
            <li>world</li>
          </ol>
        }
      </div>
    );
  },

  toggleMenu(event) {
    event.preventDefault();

    this.setState({showMenu: !this.state.showMenu});
  },
});

The prop types of the KeyHandler component are:

type Props = {
  keyValue: ?string,
  keyCode: ?number,
  keyEventName: string,
  keyName: ?string,
  onKeyHandle: Function,
};

• keyValue can be any given W3C keyboard key value
• keyCode can be any given keyboard code
• keyEventName will default to 'keyup'
• keyName can be any given character
• onKeyHandle is the function that is being called when key code is handled

You should either pass a keyValue, a keyCode or a keyName, not both.

Form key handling

This library does not handle any keys coming from an <input /> or <textarea /> element.

We recommend you to use react's built in form events for these.

If you disagree and feel very strong about this, feel free to open an issue with your reasoning and we will consider adding this functionality.

Demos

For more examples have a look at demo/components/demos/.

Development

Setup

$ git clone <this repo>
$ cd react-key-handler
$ npm install

Getting started

To start the server:

$ npm start

This starts a webpack-dev-server, which is a little node.js Express server:

$ open http://localhost:8080

Tests

To run all tests:

$ npm test

Or you can run the linters, unit tests and check for type errors individually:

$ npm run test:lint
$ npm run test:unit
$ npm run test:flow

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

 _________________
< The MIT License >
 -----------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||