{"_id":"@dhruvilshah191999/use-shortcut","_rev":"4-edadf8b8801e0432bc3ea4a135581f53","name":"@dhruvilshah191999/use-shortcut","dist-tags":{"latest":"0.2.3"},"versions":{"0.2.0":{"name":"@dhruvilshah191999/use-shortcut","version":"0.2.0","keywords":["react","hook","keyboard","shortcut","hotkey","keybinding","typescript"],"author":{"name":"Dhruvil Shah"},"license":"MIT","_id":"@dhruvilshah191999/use-shortcut@0.2.0","maintainers":[{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"}],"dist":{"shasum":"0a6cb3eb99494032ef1739cdc938137ce79306b7","tarball":"https://registry.npmjs.org/@dhruvilshah191999/use-shortcut/-/use-shortcut-0.2.0.tgz","fileCount":9,"integrity":"sha512-2bLTCT6J9N8eP4snqc2/ZkJOR/OKDLv78PUHfhyrJk+WVXHk0I+e3JMny6X1CnBF0HZ1mxMwGymcJSnrXysnBw==","signatures":[{"sig":"MEUCICjoHP4VKwFMFsTSBOps5DyC07/KGgU7KGn/MK4uY0soAiEAjuyb+RC+9oLVqFcXyeve2sk2Kt8AQRkhEmXXP3mC4N4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66480},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"d17cf8799f5218c03518ab4535ca1f0fe7a50d56","scripts":{"dev":"tsup --watch","lint":"biome check .","test":"vitest run","build":"tsup","format":"biome format --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"},"_npmVersion":"10.8.2","description":"Tiny zero-dependency React hook for keyboard shortcuts. Cross-platform, TypeScript-first.","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","_hasShrinkwrap":false,"packageManager":"pnpm@9.15.0","devDependencies":{"tsup":"^8.3.5","jsdom":"^25.0.1","react":"^18.3.1","vitest":"^2.1.8","react-dom":"^18.3.1","typescript":"^5.7.2","@types/node":"^20.17.0","@types/react":"^18.3.12","@biomejs/biome":"^1.9.4","@types/react-dom":"^18.3.1","@testing-library/react":"^16.1.0"},"peerDependencies":{"react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/use-shortcut_0.2.0_1780243712985_0.14072245948042328","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@dhruvilshah191999/use-shortcut","version":"0.2.1","keywords":["react","hook","keyboard","shortcut","hotkey","keybinding","typescript"],"author":{"name":"Dhruvil Shah"},"license":"MIT","_id":"@dhruvilshah191999/use-shortcut@0.2.1","maintainers":[{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"}],"homepage":"https://github.com/dhruvilshah191999/use-shortcut#readme","bugs":{"url":"https://github.com/dhruvilshah191999/use-shortcut/issues"},"dist":{"shasum":"722a379658076d264a37fee04f5a8c6cda1996ac","tarball":"https://registry.npmjs.org/@dhruvilshah191999/use-shortcut/-/use-shortcut-0.2.1.tgz","fileCount":9,"integrity":"sha512-ir3NKhXh0WyybFb+mgwZZmW5lV3TzfqgV7+ZI16rmF4v7pWIWJmIBBYGe63VyBhtNs1pHiKqPrYeS7xu8dFHHQ==","signatures":[{"sig":"MEQCIEtnTK7ceQ2LmRoOjez7K5B5/9QuQezBgBpeZvIkrwPvAiA3m8ZONeM6+pfkb5iCHqU0Fk3OpU82zXCmGzub2IH3/g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66754},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"253670c3e310b2befe05fe6d3cf5011e10bcce95","scripts":{"dev":"tsup --watch","lint":"biome check .","test":"vitest run","build":"tsup","format":"biome format --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"},"repository":{"url":"git+https://github.com/dhruvilshah191999/use-shortcut.git","type":"git"},"_npmVersion":"10.8.2","description":"Tiny zero-dependency React hook for keyboard shortcuts. Cross-platform, TypeScript-first.","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","_hasShrinkwrap":false,"packageManager":"pnpm@9.15.0","devDependencies":{"tsup":"^8.3.5","jsdom":"^25.0.1","react":"^18.3.1","vitest":"^2.1.8","react-dom":"^18.3.1","typescript":"^5.7.2","@types/node":"^20.17.0","@types/react":"^18.3.12","@biomejs/biome":"^1.9.4","@types/react-dom":"^18.3.1","@testing-library/react":"^16.1.0"},"peerDependencies":{"react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/use-shortcut_0.2.1_1780245177430_0.4417026587753581","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@dhruvilshah191999/use-shortcut","version":"0.2.2","keywords":["react","hook","keyboard","shortcut","hotkey","keybinding","typescript"],"author":{"name":"Dhruvil Shah"},"license":"MIT","_id":"@dhruvilshah191999/use-shortcut@0.2.2","maintainers":[{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"}],"homepage":"https://github.com/dhruvilshah191999/use-shortcut#readme","bugs":{"url":"https://github.com/dhruvilshah191999/use-shortcut/issues"},"dist":{"shasum":"4c74128994f21e0f4b21f1c08c21dcda29864c62","tarball":"https://registry.npmjs.org/@dhruvilshah191999/use-shortcut/-/use-shortcut-0.2.2.tgz","fileCount":9,"integrity":"sha512-VbrqISZm4FESTr2WwQ6Tpv4UlOzpnkkkqBFjzuK0jEwkEZ7Q7C9aIhKIk5R5/g0OUMbbnlLsISIPmqIhiOZwkg==","signatures":[{"sig":"MEUCIQDLCLvugYMau98YNd4LeKxJ5LrmRzNSOnw4lz3dMpOfhgIgTr2kCjn+DdUEqVOfw95AsLH7+dhTGWrj/g5Jg5ohwZc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73804},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"7d21f22d32dbc661c62af3dfa92319ba290876d6","scripts":{"dev":"tsup --watch","lint":"biome check .","test":"vitest run","build":"tsup","format":"biome format --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"},"repository":{"url":"git+https://github.com/dhruvilshah191999/use-shortcut.git","type":"git"},"_npmVersion":"10.8.2","description":"Tiny zero-dependency React hook for keyboard shortcuts. Cross-platform, TypeScript-first.","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","_hasShrinkwrap":false,"packageManager":"pnpm@9.15.0","devDependencies":{"tsup":"^8.3.5","jsdom":"^25.0.1","react":"^18.3.1","vitest":"^2.1.8","react-dom":"^18.3.1","typescript":"^5.7.2","@types/node":"^20.17.0","@types/react":"^18.3.12","@biomejs/biome":"^1.9.4","@types/react-dom":"^18.3.1","@testing-library/react":"^16.1.0"},"peerDependencies":{"react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/use-shortcut_0.2.2_1780500932593_0.29894438594703177","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@dhruvilshah191999/use-shortcut","version":"0.2.3","description":"Tiny zero-dependency React hook for keyboard shortcuts. Cross-platform, TypeScript-first.","license":"MIT","author":{"name":"Dhruvil Shah"},"repository":{"type":"git","url":"git+https://github.com/dhruvilshah191999/use-shortcut.git"},"homepage":"https://use-shortcut-playground.vercel.app/","bugs":{"url":"https://github.com/dhruvilshah191999/use-shortcut/issues"},"keywords":["react","hook","keyboard","shortcut","hotkey","keybinding","typescript"],"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"dev":"tsup --watch","build":"tsup","test":"vitest run","test:watch":"vitest","lint":"biome check .","format":"biome format --write .","typecheck":"tsc --noEmit","prepublishOnly":"pnpm run build"},"peerDependencies":{"react":">=18.0.0"},"devDependencies":{"@biomejs/biome":"^1.9.4","@testing-library/react":"^16.1.0","@types/node":"^20.17.0","@types/react":"^18.3.12","@types/react-dom":"^18.3.1","jsdom":"^25.0.1","react":"^18.3.1","react-dom":"^18.3.1","tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^2.1.8"},"engines":{"node":">=20"},"packageManager":"pnpm@9.15.0","_id":"@dhruvilshah191999/use-shortcut@0.2.3","gitHead":"a0037c1ae5de941cae3f84bd856d9bafc03c40ce","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-/7Pku/xrV72A2ghmlwkos/dSRGoI68Da9fMOcNw2g6BE+Gcib+3vUnHFRfNYVffH8hnosCJO42I4AcMtSYWuGA==","shasum":"027001d998335c8eb254d66e5a11d80cbc24c5ad","tarball":"https://registry.npmjs.org/@dhruvilshah191999/use-shortcut/-/use-shortcut-0.2.3.tgz","fileCount":9,"unpackedSize":73969,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHR3l5/Cy5c6uTZFo1gKGcsB3E4sXq3xUkyBD6pM/ADwAiAxVzhvsygJ8D/mX6bw/qhyhVkfIa1n6THZVI4NuflDkQ=="}]},"_npmUser":{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"},"directories":{},"maintainers":[{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/use-shortcut_0.2.3_1780507465285_0.01497416821027997"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-31T16:08:32.848Z","modified":"2026-06-03T17:24:25.558Z","0.2.0":"2026-05-31T16:08:33.124Z","0.2.1":"2026-05-31T16:32:57.570Z","0.2.2":"2026-06-03T15:35:32.742Z","0.2.3":"2026-06-03T17:24:25.431Z"},"bugs":{"url":"https://github.com/dhruvilshah191999/use-shortcut/issues"},"author":{"name":"Dhruvil Shah"},"license":"MIT","homepage":"https://use-shortcut-playground.vercel.app/","keywords":["react","hook","keyboard","shortcut","hotkey","keybinding","typescript"],"repository":{"type":"git","url":"git+https://github.com/dhruvilshah191999/use-shortcut.git"},"description":"Tiny zero-dependency React hook for keyboard shortcuts. Cross-platform, TypeScript-first.","maintainers":[{"name":"dhruvilshah191999","email":"dhruvilshah191999@gmail.com"}],"readme":"# @dhruvilshah191999/use-shortcut\n\n> Tiny zero-dependency React hook for keyboard shortcuts. Cross-platform, TypeScript-first, ~1KB gzipped.\n\n[![npm version](https://img.shields.io/npm/v/@dhruvilshah191999/use-shortcut.svg)](https://www.npmjs.com/package/@dhruvilshah191999/use-shortcut)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/@dhruvilshah191999/use-shortcut)](https://bundlephobia.com/package/@dhruvilshah191999/use-shortcut)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n**▶ [Live demo](https://use-shortcut-playground.vercel.app/)** — try every feature in your browser ([source](https://github.com/dhruvilshah191999/use-shortcut-playground)).\n\n## Install\n\n```bash\nnpm install @dhruvilshah191999/use-shortcut\npnpm add @dhruvilshah191999/use-shortcut\nyarn add @dhruvilshah191999/use-shortcut\nbun add @dhruvilshah191999/use-shortcut\n```\n\n## Usage\n\n```tsx\nimport { useShortcut } from \"@dhruvilshah191999/use-shortcut\";\n\nuseShortcut(\"mod+k\", () => setOpen(true));\n```\n\n## Why this hook?\n\n- **Zero dependencies**\n- **Tiny** (~1KB gzipped)\n- **Cross-platform out of the box**: `mod` becomes Cmd on Mac, Ctrl elsewhere\n- **Smart input field handling**: shortcuts don't fire while you're typing (except `Escape`)\n- **TypeScript types built in**\n- **Always-fresh callback**: no stale closures, no `useCallback` needed\n\n## API\n\n### `useShortcut(key, callback, options?)`\n\n| Parameter  | Type                                       | Description                                                            |\n| ---------- | ------------------------------------------ | --------------------------------------------------------------------- |\n| `key`      | `string \\| string[]`                       | A combo like `\"mod+k\"`, or an array of combos that map to one action. |\n| `callback` | `(e: KeyboardEvent) => void`               | Called with the matching event. Always the latest reference.          |\n| `options`  | `Options`                                  | Optional. See below.                                                  |\n\nCombo syntax is case-insensitive and whitespace-tolerant: `\"Cmd+K\"`, `\"cmd+k\"`, and `\" cmd + k \"` are equivalent. Supported modifier aliases: `mod`, `cmd`/`command`, `ctrl`/`control`, `alt`/`option`, `shift`, `meta`.\n\n### Options\n\n| Option            | Type                                  | Default  | Description                                                                          |\n| ----------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------ |\n| `enabled`         | `boolean`                             | `true`   | Whether the shortcut is active.                                                      |\n| `preventDefault`  | `boolean`                             | `false`  | Call `event.preventDefault()` on match.                                              |\n| `stopPropagation` | `boolean`                             | `false`  | Call `event.stopPropagation()` on match.                                             |\n| `enableInInputs`  | `boolean`                             | `false`  | Fire even while typing in inputs/textarea/select/contenteditable.                    |\n| `target`          | `RefObject<HTMLElement> \\| Window`    | `window` | Where to attach the listener. Use a ref to scope a shortcut to one element.          |\n| `scope`           | `string \\| string[]`                  | —        | Restrict the shortcut to named scope(s); fires only while one is active. See [Scopes](#scopes-optional). |\n\n## Examples\n\n### Basic\n\n```tsx\n// Cmd+K (Mac) / Ctrl+K (Windows/Linux) to open search\nuseShortcut(\"mod+k\", () => openSearch());\n```\n\n### Cross-platform\n\n```tsx\n// `mod` resolves to Cmd on Mac and Ctrl everywhere else\nuseShortcut(\"mod+s\", () => save());\n```\n\n### Multiple shortcuts for the same action\n\n```tsx\nuseShortcut([\"mod+k\", \"/\"], () => openSearch());\n```\n\n### Modal close on Escape\n\n```tsx\nuseShortcut(\"escape\", () => setOpen(false), { enabled: isOpen });\n```\n\n### Prevent default browser behavior\n\n```tsx\n// Stop the browser's native \"Save page\" dialog\nuseShortcut(\"mod+s\", () => save(), { preventDefault: true });\n```\n\n## Scopes (optional)\n\nBy default every shortcut is **global** — it fires whenever its combo matches. If you need\nthe same key to do different things in different parts of the app (list navigation vs. an\nopen modal, say), opt into **scopes**: tag a shortcut with a `scope`, wrap the relevant\nsubtree in `<ShortcutProvider>`, and activate/deactivate scopes with `useShortcutScopes()`.\n\nShortcuts **without** a `scope` stay global and need no provider — scopes are purely additive.\n\n```tsx\nimport {\n  ShortcutProvider,\n  useShortcut,\n  useShortcutScopes,\n} from \"@dhruvilshah191999/use-shortcut\";\n\nfunction App() {\n  // `list` is active on first render; `modal` is off until we open the modal\n  return (\n    <ShortcutProvider initialScopes={[\"list\"]}>\n      <List />\n      <Modal />\n    </ShortcutProvider>\n  );\n}\n\nfunction List() {\n  // fires only while the \"list\" scope is active\n  useShortcut(\"j\", selectNext, { scope: \"list\" });\n  return /* ... */;\n}\n\nfunction Modal() {\n  const { activate, deactivate } = useShortcutScopes();\n\n  function open() {\n    activate(\"modal\");   // modal shortcuts start firing\n    deactivate(\"list\");  // list shortcuts pause\n  }\n\n  // fires only while the \"modal\" scope is active\n  useShortcut(\"escape\", close, { scope: \"modal\" });\n  return /* ... */;\n}\n```\n\n`useShortcutScopes()` returns `{ activeScopes, activate, deactivate, toggle, set }`. A\nshortcut can belong to several scopes (`{ scope: [\"a\", \"b\"] }`) and fires if **any** of\nthem is active.\n\n> If you use a `scope` without a `<ShortcutProvider>`, the shortcut degrades to global\n> behavior and warns once in development.\n\n## Caveats\n\n- No sequence support (e.g., `g g`).\n- Scopes are opt-in via `<ShortcutProvider>`; without one, every shortcut is global (you can\n  also narrow a single shortcut to an element with the `target` option).\n- No priority/conflict resolution — multiple handlers for the same combo all fire. Use\n  scopes to gate which handlers are live.\n\n## When NOT to use this\n\nIf you need key sequences (e.g., `g g`), a help-modal generator, or a key-recorder UI, use [react-hotkeys-hook](https://github.com/JohannesKlauss/react-hotkeys-hook) or [TanStack Hotkeys](https://tanstack.com/hotkeys).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}