{"_id":"@amarkanala/react-keyboard-shortcuts","name":"@amarkanala/react-keyboard-shortcuts","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@amarkanala/react-keyboard-shortcuts","version":"1.0.0","description":"Modern React hooks for handling keyboard shortcuts with component-scoped event management","main":"dist/useKeyboardShortcut.js","types":"dist/useKeyboardShortcut.d.ts","type":"module","scripts":{"test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier --write \"**/*.{js,ts,tsx,json,md}\"","format:check":"prettier --check \"**/*.{js,ts,tsx,json,md}\"","build":"tsc","type-check":"tsc --noEmit"},"keywords":["react","hooks","keyboard","shortcuts","hotkeys","keybindings","react-hooks"],"author":{"name":"Amar Kanala","email":"amarkanala@gmail.com"},"license":"MIT","peerDependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0"},"devDependencies":{"@testing-library/react":"^13.4.0","@testing-library/jest-dom":"^5.16.5","@testing-library/user-event":"^14.4.3","@types/jest":"^29.5.0","@types/node":"^20.0.0","@types/react":"^18.2.0","eslint":"^8.50.0","jest":"^29.5.0","jest-environment-jsdom":"^29.5.0","prettier":"^3.0.0","react":"^18.2.0","react-dom":"^18.2.0","ts-jest":"^29.1.0","typescript":"^5.3.0"},"repository":{"type":"git","url":"git+https://github.com/amarkanala/react-keyboard-shortcuts.git"},"bugs":{"url":"https://github.com/amarkanala/react-keyboard-shortcuts/issues"},"homepage":"https://github.com/amarkanala/react-keyboard-shortcuts#readme","_id":"@amarkanala/react-keyboard-shortcuts@1.0.0","gitHead":"36f852dd7962096ddec57d793fbe99f8a0a22e69","_nodeVersion":"23.3.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-jO+SGZLlQVDaOuXBdHrdigGHWkLkGe2R+VLC+Esz5YI10eabF3qcylm4Cwd18VrJkqNZEWTUj14YHEo8btu2WA==","shasum":"018712a93f6c6c1dd927e55719a2018dabf27a49","tarball":"https://registry.npmjs.org/@amarkanala/react-keyboard-shortcuts/-/react-keyboard-shortcuts-1.0.0.tgz","fileCount":32,"unpackedSize":76675,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC62UVgoD1haTOKLOBptSa7b/nR4kFaLLE/WNuRdz9E9gIgUVqsLk77D1Uy1nFyh5++VzyoZ8EznHYH0kYlQ6/Brk8="}]},"_npmUser":{"name":"amarkanala","email":"amarkanala@gmail.com"},"directories":{},"maintainers":[{"name":"amarkanala","email":"amarkanala@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react-keyboard-shortcuts_1.0.0_1767253600812_0.3416642221365016"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-01T07:46:40.635Z","1.0.0":"2026-01-01T07:46:40.956Z","modified":"2026-01-01T07:46:41.336Z"},"maintainers":[{"name":"amarkanala","email":"amarkanala@gmail.com"}],"description":"Modern React hooks for handling keyboard shortcuts with component-scoped event management","homepage":"https://github.com/amarkanala/react-keyboard-shortcuts#readme","keywords":["react","hooks","keyboard","shortcuts","hotkeys","keybindings","react-hooks"],"repository":{"type":"git","url":"git+https://github.com/amarkanala/react-keyboard-shortcuts.git"},"author":{"name":"Amar Kanala","email":"amarkanala@gmail.com"},"bugs":{"url":"https://github.com/amarkanala/react-keyboard-shortcuts/issues"},"license":"MIT","readme":"# React Keyboard Shortcuts\n\n[![npm version](https://badge.fury.io/js/react-keyboard-shortcuts.svg)](https://badge.fury.io/js/react-keyboard-shortcuts)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm downloads](https://img.shields.io/npm/dm/react-keyboard-shortcuts.svg)](https://www.npmjs.com/package/react-keyboard-shortcuts)\n[![Node.js version](https://img.shields.io/node/v/react-keyboard-shortcuts.svg)](https://nodejs.org/)\n[![React version](https://img.shields.io/badge/react-16.8%2B-blue)](https://react.dev)\n[![GitHub Actions](https://github.com/amarkanala/react-keyboard-shortcuts/workflows/Tests/badge.svg)](https://github.com/amarkanala/react-keyboard-shortcuts/actions)\n[![Code of Conduct](https://img.shields.io/badge/Code%20of%20Conduct-Contributor%20Covenant-blue)](./CODE_OF_CONDUCT.md)\n\nA modern, lightweight React hook library for handling keyboard shortcuts with component-scoped event management. Built with React hooks and optimized for performance.\n\n---\n\n## Features\n\n- 🎯 **Component-scoped**: Shortcuts are automatically cleaned up when components unmount\n- ⚡ **Performance optimized**: Uses `useCallback` and `useMemo` for efficient re-renders\n- 🎛️ **Flexible options**: Control preventDefault, stopPropagation, and enable/disable behavior\n- 🔧 **TypeScript ready**: Full TypeScript support with proper type definitions\n- 📦 **Zero dependencies**: Only requires React 16.8+\n- 🎨 **Modern API**: Clean, intuitive hook-based API\n\n## Installation\n\n```bash\nnpm install @amarkanala/react-keyboard-shortcuts\n# or\nyarn add @amarkanala/react-keyboard-shortcuts\n```\n\n## Running Tests\n\n```bash\nnpm test\n```\n\nThe test suite covers:\n\n- Hook mounting/unmounting behavior\n- Shortcut matching and execution\n- Modifier key combinations\n- Options (preventDefault, stopPropagation, enabled)\n- Form element filtering\n- Special keys and function keys\n- Multiple shortcuts handling\n\n## Development\n\n### Code Quality\n\n```bash\n# Run linter\nnpm run lint\n\n# Fix linting issues\nnpm run lint:fix\n\n# Format code\nnpm run format\n\n# Check formatting\nnpm run format:check\n\n# Run tests with coverage\nnpm run test:coverage\n```\n\n### Code Style\n\nThis project uses:\n\n- **ESLint** for code quality\n- **Prettier** for code formatting\n- **Jest** for testing\n- **Babel** for transpilation\n\n## Supporting this Project\n\n- ⭐ Star the repository on GitHub\n- 🐛 Report bugs and issues\n- 💡 Suggest new features\n- 🤝 Contribute code improvements\n- 📢 Share with your community\n\n## Quick Example\n\nCheck out `example.js` for a complete working example, or see this simple usage:\n\n```jsx\nimport React, { useState } from 'react';\nimport { useKeyboardShortcut } from 'react-keyboard-shortcuts';\n\nfunction MyComponent() {\n const [message, setMessage] = useState('');\n\n useKeyboardShortcut('ctrl+s', (event) => {\n setMessage('File saved!');\n });\n\n return (\n
\n

{message}

\n

Press Ctrl+S to save

\n
\n );\n}\n```\n\n### Multiple Shortcuts\n\n```jsx\nimport { useKeyboardShortcuts } from 'react-keyboard-shortcuts';\n\nfunction App() {\n useKeyboardShortcuts({\n 'ctrl+s': (event) => saveDocument(),\n 'ctrl+o': (event) => openFileDialog(),\n 'ctrl+z': (event) => undo(),\n f1: (event) => showHelp(),\n esc: (event) => closeModal()\n });\n\n return
Your app content
;\n}\n```\n\n### Advanced Options\n\n```jsx\nuseKeyboardShortcut('ctrl+shift+z', redoAction, {\n preventDefault: true, // Prevent browser default (default: true)\n stopPropagation: false, // Stop event bubbling (default: false)\n enabled: canRedo // Conditionally enable/disable (default: true)\n});\n```\n\n## TypeScript Support\n\nThis library includes full TypeScript support with comprehensive type definitions.\n\n### TypeScript Example\n\n```typescript\nimport { useState, FC } from 'react';\nimport { useKeyboardShortcut, useKeyboardShortcuts } from 'react-keyboard-shortcuts';\n\nconst App: FC = () => {\n const [saved, setSaved] = useState(false);\n\n // Single shortcut with full type safety\n useKeyboardShortcut('ctrl+s', (event: KeyboardEvent): void => {\n setSaved(true);\n });\n\n // Multiple shortcuts with type inference\n useKeyboardShortcuts({\n 'ctrl+z': (): void => undo(),\n 'ctrl+y': (): void => redo(),\n esc: (): void => closeDialog(),\n });\n\n return (\n
\n {saved &&

Document saved!

}\n
\n );\n};\n\nexport default App;\n```\n\n### Type Definitions\n\nThe library exports the following TypeScript types and interfaces:\n\n```typescript\n// Single shortcut options\ninterface KeyboardShortcutOptions {\n preventDefault?: boolean;\n stopPropagation?: boolean;\n enabled?: boolean;\n}\n\n// Multiple shortcuts options\ninterface KeyboardShortcutsOptions {\n preventDefault?: boolean;\n stopPropagation?: boolean;\n enabled?: boolean;\n}\n\n// Handler function type\ntype ShortcutHandler = (event: KeyboardEvent) => void;\n\n// Shortcuts map type\ntype ShortcutsMap = Record;\n```\n\n### Building from Source\n\nTo compile TypeScript files:\n\n```bash\nnpm run build # Compile TypeScript to JavaScript\nnpm run type-check # Check types without emitting files\n```\n\n## Supported Shortcuts\n\n### Modifiers\n\n- `ctrl` / `⌃` - Control key\n- `shift` / `⇧` - Shift key\n- `alt` / `⌥` - Alt/Option key\n- `meta` / `⌘` - Command/Windows key\n\n### Special Keys\n\n- `backspace`, `tab`, `enter`, `esc`, `space`\n- Arrow keys: `left`, `up`, `right`, `down`\n- Function keys: `f1`, `f2`, ..., `f20`\n- `home`, `end`, `pageup`, `pagedown`\n- `del`, `delete`\n\n### Examples\n\n```javascript\n'ctrl+s'; // Control + S\n'shift+enter'; // Shift + Enter\n'ctrl+shift+z'; // Control + Shift + Z\n'alt+f4'; // Alt + F4\n'f1'; // F1 key\n'esc'; // Escape key\n'ctrl+o,ctrl+n'; // Multiple shortcuts (first match wins)\n```\n\n## API Reference\n\n### `useKeyboardShortcut(shortcut, handler, options?)`\n\n#### Parameters\n\n- `shortcut` (string): Keyboard shortcut combination\n- `handler` (function): Callback function receiving the keyboard event\n- `options` (object, optional): Configuration options\n\n#### Options\n\n- `preventDefault` (boolean, default: true): Call `event.preventDefault()`\n- `stopPropagation` (boolean, default: false): Call `event.stopPropagation()`\n- `enabled` (boolean, default: true): Enable/disable the shortcut\n\n### `useKeyboardShortcuts(shortcutsMap, options?)`\n\n#### Parameters\n\n- `shortcutsMap` (object): Object mapping shortcuts to handlers\n- `options` (object, optional): Configuration options\n\n#### Options\n\n- `enabled` (boolean, default: true): Enable/disable all shortcuts\n\n## Behavior\n\n- **Input filtering**: Shortcuts are ignored when focused on `input`, `select`, or `textarea` elements\n- **First match wins**: For multiple shortcuts, only the first matching combination executes\n- **Automatic cleanup**: Event listeners are removed when components unmount\n- **Performance**: Uses React's optimization hooks to prevent unnecessary re-renders\n\n## TypeScript Support\n\n```tsx\nimport { useKeyboardShortcut, useKeyboardShortcuts } from 'react-keyboard-shortcuts';\n\ninterface ShortcutOptions {\n preventDefault?: boolean;\n stopPropagation?: boolean;\n enabled?: boolean;\n}\n\nfunction useKeyboardShortcut(\n shortcut: string,\n handler: (event: KeyboardEvent) => void,\n options?: ShortcutOptions\n): void;\n\nfunction useKeyboardShortcuts(\n shortcuts: Record void>,\n options?: { enabled?: boolean }\n): void;\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes.\n","readmeFilename":"README.md","_rev":"1-83acf360e0358966ddadc255c891370c"}