{"id":13422381,"url":"https://github.com/ayrton/react-key-handler","last_synced_at":"2025-03-15T12:30:40.000Z","repository":{"id":57333611,"uuid":"52687184","full_name":"ayrton/react-key-handler","owner":"ayrton","description":"React component to handle keyboard events :key:","archived":false,"fork":false,"pushed_at":"2018-09-05T10:36:03.000Z","size":492,"stargazers_count":388,"open_issues_count":6,"forks_count":29,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-04T07:03:32.181Z","etag":null,"topics":["key-event","keyboard","react","react-component","react-components","reactjs","reactjs-component","reactjs-components"],"latest_commit_sha":null,"homepage":"http://ayrton.be/react-key-handler","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayrton.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-27T20:27:48.000Z","updated_at":"2023-08-03T07:47:56.000Z","dependencies_parsed_at":"2022-08-24T18:50:25.775Z","dependency_job_id":null,"html_url":"https://github.com/ayrton/react-key-handler","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrton%2Freact-key-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrton%2Freact-key-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrton%2Freact-key-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayrton%2Freact-key-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayrton","download_url":"https://codeload.github.com/ayrton/react-key-handler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243730942,"owners_count":20338743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["key-event","keyboard","react","react-component","react-components","reactjs","reactjs-component","reactjs-components"],"created_at":"2024-07-30T23:00:43.246Z","updated_at":"2025-03-15T12:30:39.604Z","avatar_url":"https://github.com/ayrton.png","language":"JavaScript","readme":"# react-key-handler 🔑\n\n[![npm version](https://img.shields.io/npm/v/react-key-handler.svg)](https://www.npmjs.com/package/react-key-handler) [![License](https://img.shields.io/npm/l/react-key-handler.svg)](https://www.npmjs.com/package/react-key-handler) [![Build Status](https://travis-ci.org/ayrton/react-key-handler.svg?branch=master)](https://travis-ci.org/ayrton/react-key-handler)\n\nReact component to handle keyboard events (such as `keyup`, `keydown` \u0026 `keypress`).\n\n## Testimonials\n\n\u003e \u003cdiv\u003e“Happy to see that react-key-handler is SSR safe :+1:”\u003c/div\u003e\n\u003e [Veselin Todorov](https://github.com/vesln), Chai.js core\n\n## Table of Contents\n\n1. [Installation](#installation)\n2. [Usage](#usage)\n   1. [Higher-order Components](#higher-order-components)\n   2. [Component](#component)\n   3. [Form key handling](#form-key-handling)\n3. [Key event names](#key-event-names)\n4. [`keyValue`, `code` and `keyCode`](#keyvalue-code-and-keycode)\n5. [Development](#development)\n   1. [Setup](#setup)\n   2. [Getting started](#getting-started)\n   3. [Tests](#tests)\n6. [Contributing](#contributing)\n7. [License](#license)\n\n## Installation\n\n```sh\n$ npm install react-key-handler --save\n```\n\n## Usage\n\nYou can use `react-key-handler` library in two flavours:\n\n- [higher-order components](#higher-order-components)\n- [component](#component)\n\n### Higher-order Components\n\nThis library includes two similar higher-order components, but with a different puprose:\n\n| Higher-order Component | Purpose             |\n| ---------------------- | ------------------- |\n| `keyHandler`           | Handles key changes |\n| `keyToggleHandler`     | Handles key toggles |\n\nBoth have the same API and will decorate the given component with a `keyValue`, `code`\nand `keyCode` property.\n\nInternally the `KeyHandler` component is used, for a full understanding be sure to\ncheck out [the implementation](lib/key-handler.js).\n\n```jsx\nimport React from 'react';\nimport { keyHandler, KEYPRESS } from 'react-key-handler';\n\nfunction Demo({ keyValue }) {\n  return (\n    \u003cdiv\u003e\n      {keyValue === 's' \u0026\u0026 (\n        \u003col\u003e\n          \u003cli\u003ehello\u003c/li\u003e\n          \u003cli\u003eworld\u003c/li\u003e\n        \u003c/ol\u003e\n      )}\n    \u003c/div\u003e\n  );\n}\n\nexport default keyHandler({ keyEventName: KEYPRESS, keyValue: 's' })(Demo);\n```\n\nThe prop types of the `KeyHandler` component are:\n\n| Name            | Type   | Required   | Default   |                                        |\n| --------------- | ------ | ---------- | --------- | -------------------------------------- |\n| keyEventName    | string | no         | `'keyup'` | `'keydown'`, `'keypress'` or `'keyup'` |\n| keyValue        | string | yes **\\*** |           | Any given [KeyboardEvent.key]          |\n| code            | string | yes **\\*** |           | Any given [KeyboardEvent.code]         |\n| keyCode\u0026dagger; | number | yes **\\*** |           | Any given [KeyboardEvent.keyCode]      |\n\n**\\*** You should pass at least one of these props.\n\n\u0026dagger; _Note_ that the keyCode is frequently browser specific and has therefore be set as\ndeprecated, see [MDN for details](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode).\n\n[Examples](demo/components/examples/decorators/)\n\n### Component\n\n```jsx\nimport React from 'react';\nimport KeyHandler, { KEYPRESS } from 'react-key-handler';\n\nexport default class Demo extends React.Component {\n  state = { showMenu: false };\n\n  render() {\n    const { showMenu } = this.state;\n\n    return (\n      \u003cReact.Fragment\u003e\n        \u003cKeyHandler\n          keyEventName={KEYPRESS}\n          keyValue=\"s\"\n          onKeyHandle={this.toggleMenu}\n        /\u003e\n\n        {showMenu \u0026\u0026 (\n          \u003col\u003e\n            \u003cli\u003ehello\u003c/li\u003e\n            \u003cli\u003eworld\u003c/li\u003e\n          \u003c/ol\u003e\n        )}\n      \u003c/React.Fragment\u003e\n    );\n  },\n\n  toggleMenu = (event) =\u003e {\n    event.preventDefault();\n\n    this.setState({ showMenu: !this.state.showMenu });\n  };\n}\n```\n\nThe prop types of the `KeyHandler` component are:\n\n| Name            | Type     | Required   | Default   |                                                  |\n| --------------- | -------- | ---------- | --------- | ------------------------------------------------ |\n| keyEventName    | string   | no         | `'keyup'` | `'keydown'`, `'keypress'` or `'keyup'`           |\n| keyValue        | string   | yes **\\*** |           | Any given [KeyboardEvent.key]                    |\n| code            | string   | yes **\\*** |           | Any given [KeyboardEvent.code]                   |\n| keyCode\u0026dagger; | number   | yes **\\*** |           | Any given [KeyboardEvent.keyCode]                |\n| onKeyHandle     | function | yes        |           | Function that is called when they key is handled |\n\n**\\*** You should pass at least one of these props.\n\n\u0026dagger; _Note_ that the keyCode is frequently browser specific and has therefore be set as\ndeprecated, see [MDN for details](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode).\n\n[Example](demo/components/examples/component/index.js)\n\n### Form key handling\n\nThis library does not handle key events for form elements such as `\u003cinput /\u003e` and `\u003ctextarea /\u003e`.\n\nReact does a fine job supporting these already via [keyboard events](https://reactjs.org/docs/events.html#keyboard-events).\n\n[Examples](demo/components/examples/input/)\n\n## Key event names\n\nTODO: explain the differences between the different key events.\n\n## `keyValue`, `code` and `keyCode`\n\nThe three available key events are\n\n- `keyValue` This corresponds to the true value. This is the value of the key pressed\n  by the user while taking into considerations the state of modifier keys\n  such as the `shiftKey` as well as the keyboard locale/layout\n- `code` This corresponds to the physical key on the keyboard (as opposed to the\n  character generated by pressing the key). In other words, this property\n  returns a value which isn't altered by keyboard layout or the state of\n  the modifier keys. The value is a string specific to the key, e.g. 'Digit0'\n- `keyCode` This is similar to code but numeric and also _deprecated_.\n\nWe recommend you to use the new Web standard [KeyboardEvent.key] or the [KeyboardEvent.code]\nover the deprecated [KeyboardEvent.keyCode].\n\nNote that in **React** `key` is a reserved property, and thus we use `keyValue` when referring\nto the `key` property.\n\n**Browser support:**\n\nThere's no need to worry about browser support because internally we normalize\ndeprecated HTML5 `keyValue` values and translate from legacy `keyCode` values,\nsimilar to how React does this for their `SyntheticKeyboardEvent`.\n\n**More information:**\n\n[W3C Working Draft].\n\n## Development\n\n### Setup\n\n```sh\n$ git clone \u003cthis repo\u003e\n$ cd react-key-handler\n$ npm install\n```\n\n### Getting started\n\nTo start the server:\n\n```sh\n$ npm demo\n```\n\nThis starts a development server, which will automatically rebuild the demo app as you change files and supports hot module replacement for fast development:\n\n```sh\n$ open http://localhost:1234\n```\n\n### Tests\n\nTo run all tests:\n\n```sh\n$ npm test\n```\n\nOr you can run the linters, unit tests and check for type errors individually:\n\n```sh\n$ npm run test:lint\n$ npm run test:unit\n$ npm run test:flow\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub. This project is intended to be a\nsafe, welcoming space for collaboration, and contributors are expected to adhere\nto the [Contributor Covenant](http://contributor-covenant.org/) code of conduct.\n\n## License\n\n```\n _________________\n\u003c The MIT License \u003e\n -----------------\n        \\   ^__^\n         \\  (oo)\\_______\n            (__)\\       )\\/\\\n                ||----w |\n                ||     ||\n```\n\n[w3c working draft]: https://www.w3.org/TR/DOM-Level-3-Events-key/\n[keyboardevent.key]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key\n[keyboardevent.code]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code\n[keyboardevent.keycode]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode\n[key]: https://facebook.github.io/react/docs/create-fragment.html\n","funding_links":[],"categories":["UI Utilities","UI Components","JavaScript","UI Utilites"],"sub_categories":["Device Input","Device Input/User Action"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayrton%2Freact-key-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayrton%2Freact-key-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayrton%2Freact-key-handler/lists"}