Registry / web-framework / react-hotkeys-hook

react-hotkeys-hook

library5.3.0jsnpmunverified

A React hook for declaratively handling keyboard shortcuts in components. Current stable version is 5.3.0, released with monthly cadence. It ships TypeScript definitions, supports scopes to prevent hotkey collisions, focus traps, and enables/disables scopes via context. Unlike alternatives like react-hotkeys (maintenance mode) or mousetrap (no React hook), this library is React-first with a simple hook API. Requires React >= 16.8.0. Bundle size is minimal (~2KB gzipped). ESM and CJS exports available.

web-framework

npm install react-hotkeys-hook

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-HOTKEYS-HOOK

react-hotkeys-hook

web-frameworkjavascriptv5.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useHotkeys

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

✗ import useHotkeys from 'react-hotkeys-hook'

Default export does not exist; must use named import.

useHotkeysContext

✓ import { useHotkeysContext } from 'react-hotkeys-hook'

✗ const { useHotkeysContext } = require('react-hotkeys-hook')

CommonJS require works but TypeScript users should use ESM import.

HotkeysProvider

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

✗ import { HotkeysProvider } from 'react-hotkeys-hook/hotkeys-provider'

No subpath exports; all exported from top-level package.

isHotkeyPressed

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

Added in v5.2.3; checks if a given key is currently pressed.

Options type

✓ import type { Options } from 'react-hotkeys-hook'

✗ import { Options } from 'react-hotkeys-hook'

Use type import in TypeScript for runtime-less export.

Basic example using useHotkeys with a scope dependency array. Shows increment on Ctrl+K press.

import React, { useState } from 'react'; import { useHotkeys } from 'react-hotkeys-hook'; const Example = () => { const [count, setCount] = useState(0); useHotkeys('ctrl+k', () => setCount(c => c + 1), { scopes: ['global'] }, [count]); return <p>Pressed {count} times.</p>; }; export default Example;

Debug

Known issues

breakingv5.0.0: Renamed enabledScopes to activeScopes in HotkeysProvider. Also now listens to key code instead of key, which may break custom key mappings.

fix

Rename enabledScopes prop to activeScopes. For custom key mappings, use key codes (e.g., 'KeyK' instead of 'k').

affects: >=5.0.0 <5.0.0

breakingv5.0.0: Delimiter changed from custom to always '+'. Previously custom delimiters were allowed.

fix

Use '+' exclusively to combine keys. For chord sequences, use array syntax.

affects: >=5.0.0

deprecatedv4.x: Options object keyOrder is deprecated; use orderByKeys or custom sort.

fix

Update options to use new property names as per v5 migration guide.

affects: >=4.0.0 <5.0.0

gotchauseHotkeys callback will not fire if the component is not focused unless global option is true.

fix

Pass { enabled: true } or { scopes: ['global'] } to listen globally.

affects: >=4.0.0

gotchaThe dependency array in useHotkeys must be explicitly passed for reactivity; otherwise stale closures may occur.

fix

Pass deps array as third argument or use functional state updates.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'enabledScopes')

Using v5 code with v4 API (enabledScopes renamed).

fix

Rename 'enabledScopes' to 'activeScopes' in HotkeysProvider.

Uncaught Error: useHotkeysContext must be used within a HotkeysProvider

Using useHotkeysContext but component tree lacks <HotkeysProvider>.

fix

Wrap your app with <HotkeysProvider> or avoid using context outside it.

Warning: React has detected a change in the order of Hooks called by ExampleComponent

Conditional call of useHotkeys inside a component.

fix

Always call useHotkeys unconditionally; use scopes or enabled option for conditional behavior.

Hotkey 'mod+k' not triggering on macOS

v5 uses key code 'KeyK' but 'mod' may still work; however, 'mod' is not a valid key.

fix

Use 'Meta+k' for Cmd key, or 'Control+k' for Ctrl. 'mod' is an alias but not documented.

Upgrade

Version history

5.3.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React hooks

react-domrequiredPeer dependency for React DOM bindings

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/JohannesKlauss/react-keymap-hook ↗

packagehttps://www.npmjs.com/package/react-hotkeys-hook ↗

homepagehttps://react-hotkeys-hook.vercel.app/ ↗