aarosil/react-key-handler

React component to handle keyboard events :key:

react-key-handler 🔑

React component to handle keyboard events (such as keyup, keydown & keypress).

Testimonials

“Happy to see that react-key-handler is SSR safe 👍”

[Veselin Todorov](https://github.com/vesln), Chai.js core

Table of Contents

1. Installation
2. Usage
3. Higher-order Components
4. Component
5. Form key handling
6. Key event names
7. keyValue, keyCode
8. Development
9. Contributing
10. License

Installation

$ npm install react-key-handler --save

Usage

You can use react-key-handler library in two flavours:

• higher-order components
• component

Unless you want absolute flexibility we recommend you to use a higher-order component in favour of the component.

Higher-order Components

This library includes two similar higher-order components, but with a different puprose:

Higher-order Component	Purpose
keyHandler	Handles key changes
keyToggleHandler	Handles key toggles

Both have the same API and will decorate the given component with a keyValue and keyCode property.

Internally the KeyHandler component is used, for a full understanding be sure to check out the implementation.

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

function Demo({ keyValue }) {
  return (
    <div>
      {keyValue === 's' &&
        <ol>
          <li>hello</li>
          <li>world</li>
        </ol>
      }
    </div>
  );
}

export default keyHandler({ keyEventName: KEYPRESS, keyValue: 's' })(Demo);

The prop types of the KeyHandler component are:

Name	Type	Required	Default
keyEventName	string	yes	'keyup'	'keydown', 'keypress' or 'keyup'
keyValue	string	yes *		Any given KeyboardEvent.key
keyCode	number	yes *		Any given KeyboardEvent.keyCode

* You should pass only one of these two props: keyValue or keyCode. Which one do I pick?

Examples

Component

import React from 'react';
import KeyHandler, {KEYPRESS} from 'react-key-handler';

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

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

    return (
      <div>
        <KeyHandler keyEventName={KEYPRESS} keyValue="s" 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:

Name	Type	Required	Default
keyEventName	string	yes	'keyup'	'keydown', 'keypress' or 'keyup'
keyValue	string	yes *		Any given KeyboardEvent.key
keyCode	number	yes *		Any given KeyboardEvent.keyCode
onKeyHandle	function	yes		Function that is called when they key is handled

* You should pass only one of these two props: keyValue or keyCode. Which one do I pick?

Example

Form key handling

This library does not handle key events for form elements such as <input /> and <textarea />.

React does a fine job supporting these already via keyboard events.

Examples

Key event names

TODO: explain the differences between the different key events.

keyValue, keyCode

We recommend you to use the new Web standard KeyboardEvent.key over the deprecated KeyboardEvent.keyCode.

Be cautious not to use the key property like the spec suggests, use keyValue, this is due to key being a reserved property in React.

Browser support:

There's no need to worry about browser support because internally we normalize deprecated HTML5 keyValue values and translate from legacy keyCode values, similar to how React does this for their SyntheticKeyboardEvent.

More information:

W3C Working Draft.

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 |
                ||     ||