{"id":13450454,"url":"https://github.com/JohannesKlauss/react-hotkeys-hook","last_synced_at":"2025-03-23T16:31:33.198Z","repository":{"id":37818914,"uuid":"159676569","full_name":"JohannesKlauss/react-hotkeys-hook","owner":"JohannesKlauss","description":"React hook for using keyboard shortcuts in components.","archived":false,"fork":false,"pushed_at":"2024-04-09T07:57:11.000Z","size":11372,"stargazers_count":2410,"open_issues_count":53,"forks_count":106,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-12T00:51:03.177Z","etag":null,"topics":["hook","hooks","hotkey","hotkeys","javascript","react","react-hooks","typescript"],"latest_commit_sha":null,"homepage":"https://react-hotkeys-hook.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JohannesKlauss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-11-29T14:13:20.000Z","updated_at":"2024-04-15T03:52:08.451Z","dependencies_parsed_at":"2023-10-16T16:56:11.500Z","dependency_job_id":"441ed989-ec44-4545-aa17-d956660f475c","html_url":"https://github.com/JohannesKlauss/react-hotkeys-hook","commit_stats":{"total_commits":1096,"total_committers":37,"mean_commits":29.62162162162162,"dds":0.4470802919708029,"last_synced_commit":"014464172d8b91823ac4fe85a5a748885d4ffa1f"},"previous_names":["johannesklauss/react-keymap-hook"],"tags_count":105,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohannesKlauss%2Freact-hotkeys-hook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohannesKlauss%2Freact-hotkeys-hook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohannesKlauss%2Freact-hotkeys-hook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohannesKlauss%2Freact-hotkeys-hook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JohannesKlauss","download_url":"https://codeload.github.com/JohannesKlauss/react-hotkeys-hook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221856412,"owners_count":16892438,"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":["hook","hooks","hotkey","hotkeys","javascript","react","react-hooks","typescript"],"created_at":"2024-07-31T07:00:34.789Z","updated_at":"2024-10-28T16:31:21.148Z","avatar_url":"https://github.com/JohannesKlauss.png","language":"TypeScript","funding_links":[],"categories":["Packages","TypeScript","Uncategorized"],"sub_categories":["Uncategorized"],"readme":"\u003chr\u003e\n\u003cdiv align=\"center\"\u003e\n \u003ch1 align=\"center\"\u003e\n useHotkeys(keys, callback)\n \u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n \u003ca href=\"https://bundlephobia.com/result?p=react-hotkeys-hook\"\u003e\n \u003cimg alt=\"Bundlephobia\" src=\"https://img.shields.io/bundlephobia/minzip/react-hotkeys-hook?style=for-the-badge\u0026labelColor=24292e\"\u003e\n \u003c/a\u003e\n \u003ca aria-label=\"Types\" href=\"https://www.npmjs.com/package/react-hotkeys-hook\"\u003e\n \u003cimg alt=\"Types\" src=\"https://img.shields.io/npm/types/react-hotkeys-hook?style=for-the-badge\u0026labelColor=24292e\"\u003e\n \u003c/a\u003e\n \u003ca aria-label=\"NPM version\" href=\"https://www.npmjs.com/package/react-hotkeys-hook\"\u003e\n \u003cimg alt=\"NPM Version\" src=\"https://img.shields.io/npm/v/react-hotkeys-hook?style=for-the-badge\u0026labelColor=24292e\"\u003e\n \u003c/a\u003e\n \u003ca aria-label=\"License\" href=\"https://jaredlunde.mit-license.org/\"\u003e\n \u003cimg alt=\"MIT License\" src=\"https://img.shields.io/npm/l/react-hotkeys-hook?style=for-the-badge\u0026labelColor=24292e\"\u003e\n \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n \u003ca aria-label=\"Sponsored by Spaceteams\" href=\"https://spaceteams.de\"\u003e\n \u003cimg alt=\"Sponsored by Spaceteams\" src=\"https://raw.githubusercontent.com/spaceteams/badges/main/sponsored-by-spaceteams.svg\"\u003e\n \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cpre align=\"center\"\u003enpm i react-hotkeys-hook\u003c/pre\u003e\n\n\u003cp align=\"center\"\u003e\nA React hook for using keyboard shortcuts in components in a declarative way.\n\u003c/p\u003e\n\n\u003chr\u003e\n\n## Quick Start\n\nThe easiest way to use the hook.\n\n```jsx harmony\nimport { useHotkeys } from 'react-hotkeys-hook'\n\nexport const ExampleComponent = () =\u003e {\n const [count, setCount] = useState(0)\n useHotkeys('ctrl+k', () =\u003e setCount(count + 1), [count])\n\n return (\n \u003cp\u003e\n Pressed {count} times.\n \u003c/p\u003e\n )\n}\n```\n\n### Scopes\n\nScopes allow you to group hotkeys together. You can use scopes to prevent hotkeys from colliding with each other.\n\n```jsx harmony\nconst App = () =\u003e {\n return (\n \u003cHotkeysProvider initiallyActiveScopes={['settings']}\u003e\n \u003cExampleComponent /\u003e\n \u003c/HotkeysProvider\u003e\n )\n}\n\nexport const ExampleComponent = () =\u003e {\n const [count, setCount] = useState(0)\n useHotkeys('ctrl+k', () =\u003e setCount(prevCount =\u003e prevCount + 1), { scopes: ['settings'] })\n\n return (\n \u003cp\u003e\n Pressed {count} times.\n \u003c/p\u003e\n )\n}\n```\n\n#### Changing a scope's active state\n\nYou can change the active state of a scope using the `disableScope`, `enableScope` and `toggleScope` functions\nreturned by the `useHotkeysContext()` hook. Note that you have to have your app wrapped in a `\u003cHotkeysProvider\u003e` component.\n\n```jsx harmony\nconst App = () =\u003e {\n return (\n \u003cHotkeysProvider initiallyActiveScopes={['settings']}\u003e\n \u003cExampleComponent /\u003e\n \u003c/HotkeysProvider\u003e\n )\n}\n\nexport const ExampleComponent = () =\u003e {\n const { toggleScope } = useHotkeysContext()\n\n return (\n \u003cbutton onClick={() =\u003e toggleScope('settings')}\u003e\n Change scope active state\n \u003c/button\u003e\n )\n}\n```\n\n### Focus trap\n\nThis will only trigger the hotkey if the component is focused.\n\n```tsx harmony\nexport const ExampleComponent = () =\u003e {\n const [count, setCount] = useState(0)\n const ref = useHotkeys\u003cHTMLParagraphElement\u003e('ctrl+k', () =\u003e setCount(prevCount =\u003e prevCount + 1))\n\n return (\n \u003cp tabIndex={-1} ref={ref}\u003e\n Pressed {count} times.\n \u003c/p\u003e\n )\n}\n```\n\n## Documentation \u0026 Live Examples\n\n* [Quick Start](https://react-hotkeys-hook.vercel.app/docs/intro)\n* [Documentation](https://react-hotkeys-hook.vercel.app/docs/documentation/installation)\n* [API](https://react-hotkeys-hook.vercel.app/docs/api/use-hotkeys)\n\n## API\n\n### useHotkeys(keys, callback)\n\n```typescript\nuseHotkeys(keys: string | string[], callback: (event: KeyboardEvent, handler: HotkeysEvent) =\u003e void, options: Options = {}, deps: DependencyList = [])\n```\n\n| Parameter | Type | Required? | Default value | Description |\n|---------------|---------------------------------------------------------|-----------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `keys` | `string` or `string[]` | required | - | set the hotkeys you want the hook to listen to. You can use single or multiple keys, modifier combinations, etc. This will either be a string or an array of strings. To separate multiple keys, use a comma. This split key value can be overridden with the `splitKey` option. |\n| `callback` | `(event: KeyboardEvent, handler: HotkeysEvent) =\u003e void` | required | - | This is the callback function that will be called when the hotkey is pressed. The callback will receive the browsers native `KeyboardEvent` and the libraries `HotkeysEvent`. |\n| `options` | `Options` | optional | `{}` | Object to modify the behavior of the hook. Default options are given below. |\n| `dependencies` | `DependencyList` | optional | `[]` | The given callback will always be memoised inside the hook. So if you reference any outside variables, you need to set them here for the callback to get updated (Much like `useCallback` works in React). |\n\n### Options\n\nAll options are optional and have a default value which you can override to change the behavior of the hook.\n\n| Option | Type | Default value | Description |\n|--------------------------|--------------------------------------------------------------------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `enabled` | `boolean` or `(keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) =\u003e boolean` | `true` | This option determines whether the hotkey is active or not. It can take a boolean (for example a flag from a state outside) or a function which gets executed once the hotkey is pressed. If the function returns `false` the hotkey won't get executed and all browser events are prevented. |\n| `enableOnFormTags` | `boolean` or `FormTags[]` | `false` | By default hotkeys are not registered if a focus focuses on an input field. This will prevent accidental triggering of hotkeys when the user is typing. If you want to enable hotkeys, use this option. Setting it to true will enable on all form tags, otherwise you can give an array of form tags to enable the hotkey on (possible options are: `['input', 'textarea', 'select']`) |\n| `enableOnContentEditable` | `boolean` | `false` | Set this option to enable hotkeys on tags that have set the `contentEditable` prop to `true` |\n| `combinationKey` | `string` | `+` | Character to indicate keystrokes like `shift+c`. You might want to change this if you want to listen to the `+` character like `ctrl-+`. |\n| `splitKey` | `string` | `,` | Character to separate different keystrokes like `ctrl+a, ctrl+b`. |\n| `scopes` | `string` or `string[]` | `*` | With scopes you can group hotkeys together. The default scope is the wildcard `*` which matches all hotkeys. Use the `\u003cHotkeysProvider\u003e` component to change active scopes. |\n| `keyup` | `boolean` | `false` | Determines whether to listen to the browsers `keyup` event for triggering the callback. |\n| `keydown` | `boolean` | `true` | Determines whether to listen to the browsers `keydown` event for triggering the callback. If you set both `keyup`and `keydown` to true, the callback will trigger on both events. |\n| `preventDefault` | `boolean` or `(keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) =\u003e boolean` | `false` | Set this to a `true` if you want the hook to prevent the browsers default behavior on certain keystrokes like `meta+s` to save a page. NOTE: Certain keystrokes are not preventable, like `meta+w` to close a tab in chrome. |\n| `description` | `string` | `undefined` | Use this option to describe what the hotkey does. this is helpful if you want to display a list of active hotkeys to the user. |\n\n\n#### Overloads\n\nThe hooks call signature is very flexible. For example if you don't need to set any special options you can use the dependency\narray as your third parameter:\n\n`useHotkeys('ctrl+k', () =\u003e console.log(counter + 1), [counter])`\n\n### `isHotkeyPressed(keys: string | string[], splitKey?: string = ',')`\n\nThis function allows us to check if the user is currently pressing down a key.\n\n```ts\nimport { isHotkeyPressed } from 'react-hotkeys-hook'\n\nisHotkeyPressed('esc') // Returns true if Escape key is pressed down.\n```\n\nYou can also check for multiple keys at the same time:\n\n```ts\nisHotkeyPressed(['esc', 'ctrl+s']) // Returns true if Escape or Ctrl+S are pressed down.\n```\n\n## Support\n\n* Ask your question in the [Github Discussions]([Support](https://github.com/JohannesKlauss/react-hotkeys-hook/discussions))\n* Ask your question on [StackOverflow](https://stackoverflow.com/search?page=1\u0026tab=Relevance\u0026q=react-hotkeys-hook)\n\n## Found an issue or have a feature request?\n\nOpen up an [issue](https://github.com/JohannesKlauss/react-hotkeys-hook/issues/new)\nor [pull request](https://github.com/JohannesKlauss/react-hotkeys-hook/compare) and participate.\n\n## Local Development\n\nCheckout this repo, run `yarn` or `npm i` and then run the `test` script to test the behavior of the hook.\n\n## Contributing\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\nDistributed under the MIT License. See `LICENSE` for more information.\n\n## Contact\n\nJohannes Klauss - [@JohannesKlauss](https://github.com/JohannesKlauss) - klauss.johannes@gmail.com\n\nProject Link: [https://github.com/JohannesKlauss/react-hotkeys-hook](https://github.com/JohannesKlauss/react-hotkeys-hook)\n\n## Contributors\n\n\u003ca href=\"https://github.com/johannesklauss/react-hotkeys-hook/graphs/contributors\"\u003e\n \u003cimg src=\"https://contrib.rocks/image?repo=johannesklauss/react-hotkeys-hook\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJohannesKlauss%2Freact-hotkeys-hook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJohannesKlauss%2Freact-hotkeys-hook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJohannesKlauss%2Freact-hotkeys-hook/lists"}