react-hotkeys-hook

To scope hotkeys to container elements like <div>, <section>, or <span>, you must make them focusable. Add a tabIndex={-1} attribute to the element. This allows the element to receive focus via JavaScript or mouse clicks (enabling the scoped hotkey) without adding the element to the natural keyboard tab order of the page.

function ScopedHotkey() {
  const [count, setCount] = useState(0)
  const ref = useHotkeys('shift+a', () => setCount(prevCount => prevCount + 1))

  return (
    <div ref={ref} tabIndex={-1} style={{border: '2px solid #9e768f', padding: '12px'}}>
      <p>The count is {count}. Click inside this area to enable the hotkey.</p>
    </div>
  )
}

The enabledScopes property in the useHotkeysContext() hook has been renamed to activeScopes to avoid confusion with the enableScope method.

// v4
const { enabledScopes } = useHotkeysContext()

// v5
const { activeScopes } = useHotkeysContext()

You can deploy the website using different methods depending on your hosting setup:

Using SSH:

$ USE_SSH=true yarn deploy

Using GitHub Pages (Non-SSH): Provide your GitHub username to build the site and push it to the gh-pages branch.

$ GIT_USER=<Your GitHub username> yarn deploy

Install the react-hotkeys-hook package using npm, bun, or yarn to use it in your React project.

npm i react-hotkeys-hook
# or
bun i react-hotkeys-hook
# or
yarn add react-hotkeys-hook

To use the library, import the useHotkeys hook from react-hotkeys-hook.

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

To start a local development server that reflects changes live, use the yarn start command. This will also open a browser window automatically.

$ yarn start

The option names for combining and separating keys have been renamed in version 5 to improve clarity.

Migration Example:

// v4
useHotkeys('ctrl+a, shift+b', callback, { combinationKey: '-', splitKey: ';' })

// v5
useHotkeys('ctrl+a, shift+b', callback, { splitKey: '-', delimiter: ';' })

Use HotkeysProvider to group hotkeys into named scopes. This allows you to enable or disable entire groups of hotkeys simultaneously (e.g., when opening a modal). Wrapping your application with this provider also enables the wildcard scope * by default.

import { HotkeysProvider } from 'react-hotkeys-hook';

function App() {
  return (
    <HotkeysProvider>
      <div>
        <h1>My App</h1>
      </div>
    </HotkeysProvider>
  )
}

When using the ref returned by useHotkeys to scope hotkeys to non-interactive elements (like <div>, <span>, or <p>), you must add a tabIndex prop to the element. Without tabIndex, these elements cannot receive focus and the scoped hotkey will not trigger.

function App() {
  const [count, setCount] = useState(0);
  const ref = useHotkeys("s", () => setCount((prevCount) => prevCount + 1));

  return (
    <div>
      <div style={{ padding: "30px" }}>Count: {count}</div>
      <div style={{ padding: "30px", background: "teal" }} tabIndex={0}>
        Focusing this area won't trigger the hotkey.
      </div>
      <div style={{ padding: "30px", background: "crimson" }} ref={ref} tabIndex={0}>
        Focusing this area will trigger the hotkey.
      </div>
    </div>
  );
}

If you want a hotkey to trigger based on the character produced (layout-dependent), pass { useKey: true } in the options object. This ensures that the shortcut triggers whenever the user produces the specific character, regardless of which physical keys they press to get there.

This is recommended when your UI shows a character hint (e.g., "Press ? for help") and you want that shortcut to work across different keyboard layouts.

function ExampleComponent() {
  const [count, setCount] = useState(0)
  // Listens for the actual '!' character
  useHotkeys('!', () => setCount(prevCount => prevCount + 1), { useKey: true })

  return (
    <span>Pressed the '!' key {count} times.</span>
  )
}

Use the useHotkeys hook to register a keyboard shortcut. The hook takes a key combination string and a callback function that executes when the keys are pressed.

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>
  )
}