React component to handle keyboard events
npm install @banzai-inc/react-key-handler  
React component to handle keyboard events (such as keyup, keydown & keypress).
- react-key-handler 🔑
- Changes for banzai:
- Table of Contents
- Installation
- Usage
- Higher-order Components
- Component
- Form key handling
- Key event names
- keyValue, code and keyCode
- Development
- Setup
- Getting started
- Tests
- Contributing
- License
``sh`
$ npm install react-key-handler --save
You can use react-key-handler library in two flavours:
- higher-order components
- component
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, codekeyCode
and property.
Internally the KeyHandler component is used, for a full understanding be sure to
check out the implementation.
`jsx
import React from 'react';
import { keyHandler, KEYPRESS } from 'react-key-handler';
function Demo({ keyValue }) {
return (
export default keyHandler({ keyEventName: KEYPRESS, keyValue: 's' })(Demo);
`
The prop types of the KeyHandler component are:
| Name | Type | Required | Default | |
| --------------- | ------ | ---------- | --------- | -------------------------------------- |
| keyEventName | string | no | 'keyup' | 'keydown', 'keypress' or 'keyup' |
| keyValue | string | yes \* | | Any given [KeyboardEvent.key] |
| code | string | yes \* | | Any given [KeyboardEvent.code] |
| keyCode† | number | yes \* | | Any given [KeyboardEvent.keyCode] |
\* You should pass at least one of these props.
† _Note_ that the keyCode is frequently browser specific and has therefore be set as
deprecated, see MDN for details.
`jsx
import React from 'react';
import KeyHandler, { KEYPRESS } from 'react-key-handler';
export default class Demo extends React.Component {
state = { showMenu: false };
render() {
const { showMenu } = this.state;
return (
keyValue="s"
onKeyHandle={this.toggleMenu}
/>
{showMenu && (
toggleMenu = (event) => {
event.preventDefault();
this.setState({ showMenu: !this.state.showMenu });
};
}
`
The prop types of the KeyHandler component are:
| Name | Type | Required | Default | |
| --------------- | -------- | ---------- | --------- | ------------------------------------------------ |
| keyEventName | string | no | 'keyup' | 'keydown', 'keypress' or 'keyup' |
| keyValue | string | yes \* | | Any given [KeyboardEvent.key] |
| code | string | yes \* | | Any given [KeyboardEvent.code] |
| keyCode† | number | yes \* | | Any given [KeyboardEvent.keyCode] |
| onKeyHandle | function | yes | | Function that is called when they key is handled |
\* You should pass at least one of these props.
† _Note_ that the keyCode is frequently browser specific and has therefore be set as
deprecated, see MDN for details.
This library does not handle key events for form elements such as and .
React does a fine job supporting these already via keyboard events.
TODO: explain the differences between the different key events.
, code and keyCodeThe three available key events are
- keyValue This corresponds to the true value. This is the value of the key pressedshiftKey
by the user while taking into considerations the state of modifier keys
such as the as well as the keyboard locale/layoutcode
- This corresponds to the physical key on the keyboard (as opposed to thekeyCode
character generated by pressing the key). In other words, this property
returns a value which isn't altered by keyboard layout or the state of
the modifier keys. The value is a string specific to the key, e.g. 'Digit0'
- This is similar to code but numeric and also _deprecated_.
We recommend you to use the new Web standard [KeyboardEvent.key] or the [KeyboardEvent.code]
over the deprecated [KeyboardEvent.keyCode].
Note that in React key is a reserved property, and thus we use keyValue when referringkey
to the property.
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,SyntheticKeyboardEvent
similar to how React does this for their .
More information:
[W3C Working Draft].
`sh`
$ git clone
$ cd react-key-handler
$ npm install
To start the server:
`sh`
$ 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:
`sh`
$ open http://localhost:1234
To run all tests:
`sh`
$ npm test
Or you can run the linters, unit tests and check for type errors individually:
`sh`
$ 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 a
safe, welcoming space for collaboration, and contributors are expected to adhere
to the Contributor Covenant code of conduct.
```
_________________
< The MIT License >
-----------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
[w3c working draft]: https://www.w3.org/TR/DOM-Level-3-Events-key/
[keyboardevent.key]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key
[keyboardevent.code]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code
[keyboardevent.keycode]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode
[key]: https://facebook.github.io/react/docs/create-fragment.html