Repository files navigation

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

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

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

1. Installation
2. Usage
   1. Higher-order Components
   2. Component
   3. Form key handling
3. Key event names
4. keyValue,code andkeyCode
5. Development
   1. Setup
   2. Getting started
   3. Tests
6. Contributing
7. License

$ npm install react-key-handler --save

You can usereact-key-handler library in two flavours:

• higher-order components
• component

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

Both have the same API and will decorate the given component with akeyValue,codeandkeyCode property.

Internally theKeyHandler component is used, for a full understanding be sure tocheck outthe implementation.

importReactfrom'react';import{keyHandler,KEYPRESS}from'react-key-handler';functionDemo({ keyValue}){return(<div>{keyValue==='s'&&(<ol><li>hello</li><li>world</li></ol>)}</div>);}exportdefaultkeyHandler({keyEventName:KEYPRESS,keyValue:'s'})(Demo);

The prop types of theKeyHandler component are:

* You should pass at least one of these props.

†Note that the keyCode is frequently browser specific and has therefore be set asdeprecated, seeMDN for details.

Examples

importReactfrom'react';importKeyHandler,{KEYPRESS}from'react-key-handler';exportdefaultclassDemoextendsReact.Component{state={showMenu:false};render(){const{ showMenu}=this.state;return(<React.Fragment><KeyHandlerkeyEventName={KEYPRESS}keyValue="s"onKeyHandle={this.toggleMenu}/>{showMenu&&(<ol><li>hello</li><li>world</li></ol>)}</React.Fragment>);},toggleMenu=(event)=>{event.preventDefault();this.setState({showMenu:!this.state.showMenu});};}

The prop types of theKeyHandler component are:

* You should pass at least one of these props.

†Note that the keyCode is frequently browser specific and has therefore be set asdeprecated, seeMDN for details.

Example

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

React does a fine job supporting these already viakeyboard events.

Examples

TODO: explain the differences between the different key events.

The three available key events are

• keyValue This corresponds to the true value. This is the value of the key pressedby the user while taking into considerations the state of modifier keyssuch as theshiftKey as well as the keyboard locale/layout
• code This corresponds to the physical key on the keyboard (as opposed to thecharacter generated by pressing the key). In other words, this propertyreturns a value which isn't altered by keyboard layout or the state ofthe modifier keys. The value is a string specific to the key, e.g. 'Digit0'
• keyCode This is similar to code but numeric and alsodeprecated.

We recommend you to use the new Web standardKeyboardEvent.key or theKeyboardEvent.codeover the deprecatedKeyboardEvent.keyCode.

Note that inReactkey is a reserved property, and thus we usekeyValue when referringto thekey property.

Browser support:

There's no need to worry about browser support because internally we normalizedeprecated HTML5keyValue values and translate from legacykeyCode values,similar to how React does this for theirSyntheticKeyboardEvent.

More information:

W3C Working Draft.

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

To start the server:

$ npm demo

This starts a development server, which will automatically rebuild the demo app as you change files and supports hot module replacement for fast development:

$ open http://localhost:1234

To run all tests:

$ npmtest

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

Bug reports and pull requests are welcome on GitHub. This project is intended to be asafe, welcoming space for collaboration, and contributors are expected to adhereto theContributor Covenant code of conduct.

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