react-hotkeys-hook

What is react-hotkeys-hook?

The react-hotkeys-hook package is a React hook for handling keyboard shortcuts. It allows developers to easily add keyboard shortcuts to their React applications, making it easier to enhance user interactions and accessibility.

What are react-hotkeys-hook's main functionalities?

Basic Key Binding

This feature allows you to bind a specific key combination to a function. In this example, pressing 'Ctrl+K' will trigger an alert.

```jsx
import React from 'react';
import { useHotkeys } from 'react-hotkeys-hook';

const App = () => {
  useHotkeys('ctrl+k', () => alert('Ctrl+K pressed!'));

  return (
    <div>
      <h1>Press Ctrl+K</h1>
    </div>
  );
};

export default App;
```

Multiple Key Bindings

This feature allows you to bind multiple key combinations to a single function. In this example, pressing either 'Ctrl+K' or 'Ctrl+L' will trigger an alert.

```jsx
import React from 'react';
import { useHotkeys } from 'react-hotkeys-hook';

const App = () => {
  useHotkeys('ctrl+k, ctrl+l', () => alert('Ctrl+K or Ctrl+L pressed!'));

  return (
    <div>
      <h1>Press Ctrl+K or Ctrl+L</h1>
    </div>
  );
};

export default App;
```

Scoped Key Bindings

This feature allows you to bind key combinations within specific scopes. In this example, 'Ctrl+K' can be bound to different functions in different components or contexts.

```jsx
import React from 'react';
import { useHotkeys } from 'react-hotkeys-hook';

const App = () => {
  useHotkeys('ctrl+k', () => alert('Ctrl+K pressed!'), { scopes: ['scope1'] });

  return (
    <div>
      <h1>Press Ctrl+K</h1>
    </div>
  );
};

const AnotherComponent = () => {
  useHotkeys('ctrl+k', () => alert('Ctrl+K pressed in another component!'), { scopes: ['scope2'] });

  return (
    <div>
      <h1>Press Ctrl+K in Another Component</h1>
    </div>
  );
};

export default App;
```

Other packages similar to react-hotkeys-hook

react-hotkeys

react-hotkeys is a mature library for handling keyboard shortcuts in React applications. It provides a more comprehensive API for managing key events and supports nested hotkey scopes. Compared to react-hotkeys-hook, it offers more advanced features but may require more setup.

react-shortcuts

react-shortcuts is another library for handling keyboard shortcuts in React. It focuses on simplicity and ease of use, similar to react-hotkeys-hook. However, it may not offer as many advanced features or customization options as react-hotkeys-hook.

react-keyboard-event-handler

react-keyboard-event-handler is a lightweight library for handling keyboard events in React. It is easy to use and provides basic functionality for key bindings. It is similar to react-hotkeys-hook in terms of simplicity but may lack some of the more advanced features.

README

---

useHotkeys(key, handler)

npm i react-hotkeys-hook

A React hook for using keyboard shortcuts in components.

---

Quick Start

import { useHotkeys } from 'react-hotkeys-hook'

export const ExampleComponent = () => {
  const [count, setCount] = useState(0)
  useHotkeys('ctrl+k', () => setCount(prevCount => prevCount + 1))

  return (
    <p>
      Pressed {count} times.
    </p>
  )
}

The hook takes care of all the binding and unbinding for you. As soon as the component mounts into the DOM, the key stroke will be listened to. When the component unmounts it will stop listening.

Documentation & Live Examples

• Quick Start
• Documentation
• API

Join the discussion for version 4!

If you use this package please share your thoughts on how we can improve this hook with version 4. Please engage at the corresponding Github issue.

API

useHotkeys()

useHotkeys(keys: string, callback: (event: KeyboardEvent, handler: HotkeysEvent) => void, options: Options = {}, deps: any[] = [])

Parameters

• keys: string: Here you can set the key strokes you want the hook to listen to. You can use single or multiple keys, modifier combination, etc. See this section on the hotkeys documentation for more info.
• callback: (event: KeyboardEvent, handler: HotkeysEvent) => void: Gets executed when the defined keystroke gets hit by the user. Important: Since version 1.5.0 this callback gets memoised inside the hook. So you don't have to do this anymore by yourself.
• options: Options = {}
  • filter: (event: KeyboardEvent): boolean is used to filter if a callback gets triggered depending on the keyboard event. Breaking Change in 3.0.0! Prior to version 3.0.0 the filter settings was one global setting that applied to every hook. Since 3.0.0 this behavior changed. The filter option is now locally scoped to each call of useHotkeys.
  • filterPreventDefault: boolean is used to prevent/allow the default browser behavior for the keystroke when the filter return false (default value: true)
  • enableOnTags: string[] is used to enable listening to hotkeys in form fields. Available values are INPUT, TEXTAREA and SELECT.
  • splitKey: string is used to change the splitting character inside the keys argument. Default is +, but if you want to listen to the + character, you can set splitKey to i.e. - and listen for ctrl-+
  • keyup: boolean Determine if you want to listen on the keyup event
  • keydown: boolean Determine if want to listen on the keydown event
  • enabled: boolean is used to prevent installation of the hotkey when set to false (default value: true)
• deps: any[] = []: The dependency array that gets appended to the memoisation of the callback. Here you define the inner dependencies of your callback. If for example your callback actions depend on a referentially unstable value or a value that will change over time, you should add this value to your deps array. Since most of the time your callback won't depend on any unstable callbacks or changing values over time you can leave this value alone since it will be set to an empty array by default. See the Memoisation section to learn more and see an example where you have to set this array.

isHotkeyPressed function

This function allows us to check if the user is currently pressing down a key.

import { isHotkeyPressed } from 'react-hotkeys-hook'

isHotkeyPressed('return') // Returns true if Return key is pressed down.

Support

• Ask your question in the Github Discussions
• Ask your question on StackOverflow

Found an issue or have a feature request?

Open up an issue or pull request and participate.

Local Development

Checkout this repo, run yarn or npm i and then run the test script to test the behavior of the hook.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Johannes Klauss - @JohannesKlauss - [e-mail]

Project Link: https://github.com/JohannesKlauss/react-hotkeys-hook

Contributors

• bernatmv
• wheeler
• louisrli
• jameschao
• hmafzal
• godspeedelbow
• JoshuaKGoldberg
• ggascoigne