{"id":26897076,"url":"https://github.com/pato12/modern-hotkeys","last_synced_at":"2025-05-12T23:42:08.772Z","repository":{"id":62186403,"uuid":"557893820","full_name":"pato12/modern-hotkeys","owner":"pato12","description":"Brand new library to create keyboard shortcuts using modern APIs. It has no dependencies.","archived":false,"fork":false,"pushed_at":"2023-02-18T16:06:18.000Z","size":354,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-12T23:41:59.707Z","etag":null,"topics":["binding","hotkeys","key","keymap","shortcuts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pato12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-26T13:59:52.000Z","updated_at":"2023-10-17T11:40:02.000Z","dependencies_parsed_at":"2025-04-01T04:41:28.306Z","dependency_job_id":"d2877538-7088-4423-a3ea-8d0bd2afa861","html_url":"https://github.com/pato12/modern-hotkeys","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pato12%2Fmodern-hotkeys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pato12%2Fmodern-hotkeys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pato12%2Fmodern-hotkeys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pato12%2Fmodern-hotkeys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pato12","download_url":"https://codeload.github.com/pato12/modern-hotkeys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253843170,"owners_count":21972867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binding","hotkeys","key","keymap","shortcuts"],"created_at":"2025-04-01T04:41:21.466Z","updated_at":"2025-05-12T23:42:08.738Z","avatar_url":"https://github.com/pato12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# modern-hotkeys\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/modern-hotkeys\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dt/modern-hotkeys\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/modern-hotkeys\"\u003e\n  \u003cimg src=\"https://img.shields.io/bundlephobia/minzip/modern-hotkeys?label=size\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/pato12/modern-hotkeys?style=social\"\u003e\n\u003c/p\u003e\n\nmodern-hotkeys is a library that makes it easy to create hotkeys for your applications. It uses modern APIs and supports multiple combinations of keyboard layouts. Furthermore, its customizable event filter and scope system allows you to easily add hotkeys to any part of your application. You can create a smooth and reliable hotkey experience for your users. It has no dependencies.\n\n## How to install\n\n```\nyarn add modern-hotkeys\n```\n\nor\n\n```\nnpm i modern-hotkeys\n```\n\n# Usage\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys('shift + a', (event, handler) =\u003e {\n  // it always prevents default\n  console.log('You pressed shift + a!');\n});\n```\n\n# Main difference with Hotkeys\n\n- Always prevent default all events\n- Set an order in your shortcuts\n- Stop propagation if you have multiple shorcuts with the same keys\n- Use modern [APIs](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code)\n- Prepared to work with different keyboard layouts such as Spanish (by default it's enUS)\n- Create your own instance\n\n# Supported Keys\n\nModern HotKeys understands the following modifiers: `⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `⌃`, `command`, and `⌘`.\n\nTo see all supported keys check out the layouts:\n\n- [en-us](./src/layouts/en-us.ts)\n- [es-es](./src/layouts/es-es.ts)\n- [es-la](./src/layouts/es-la.ts)\n\nIf you need another layout you can create using the interface `KeyboardLayout`.\n\n```ts\nimport { KeyboardLayout, hotkeys } from 'modern-hotkeys';\n\nconst MyLayout: KeyboardLayout = {\n  Backspace: { value: 'backspace' },\n  Tab: { value: 'tab' },\n  NumLock: { value: 'NumLock' },\n  ...\n};\n\nhotkeys.setKeyboardLayout(MyLayout);\n```\n\n# Define a shortcut\n\nWe export a global instance but you can create your own one.\n\nUsing the global instance\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys('command + s, ctrl + s', () =\u003e {\n  alert('saving!');\n});\n```\n\nCreating own instance\n\n```ts\nimport { createHotkeys } from 'modern-hotkeys';\n\nconst instance = createHotkeys({ element: document.body });\n\ninstance.hotkeys('command + s, ctrl + s', () =\u003e {\n  alert('saving!');\n});\n```\n\n## API references\n\n## createHotkeys\n\nCreates a new instance of `hotkeys` with the specified options.\n\n### Parameters\n\n- `element` (`HTMLElement`): Element to bind events to.\n- `keyboard` (`KeyboardLayout`): Keyboard layout to use. Default is `Layouts['en-us']`.\n- `autoWatchKeys` (`boolean`): Whether to automatically watch for keys. Default is `true`.\n- `watchCaps` (`boolean`): Whether to watch for the `CapsLock` key. Default is `false`.\n- `autoPreventDefault` (`boolean`): Whether to automatically prevent default. Default is `true`.\n\n## scope\n\nScopes allow you to isolate your shortcuts and only execute depending on the scope that your app is running.\n\n```tsx\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys('command + s, ctrl + s', 'file', () =\u003e {\n  alert('saving file! you are in the scope ' + hotkeys.getScope());\n});\n\n\u003cbutton onClick={() =\u003e hotkeys.setScope('file')}\u003eset file scope\u003c/button\u003e;\n\n// or if you have your instance\n\nimport { createHotkeys } from 'modern-hotkeys';\n\nconst instance = createHotkeys({ element: document.body });\n\ninstance.hotkeys('command + s, ctr + s', 'file', () =\u003e {\n  alert('saving file! you are in the scope ' + instance.getScope());\n});\n\n\u003cbutton onClick={() =\u003e instance.setScope('file')}\u003eset file scope\u003c/button\u003e;\n```\n\n## getKeysDown\n\nReturns a `Set` with all keys down.\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys('a, b, c', () =\u003e {\n  console.log(hotkeys.getKeysDown().has('a'));\n  console.log(hotkeys.getKeysDown().has('b'));\n  console.log(hotkeys.getKeysDown().has('c'));\n});\n```\n\n## isPressed\n\nReturn a boolean to know if a key is pressed\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys('a, b, c', () =\u003e {\n  console.log(hotkeys.isPressed('a'));\n  console.log(hotkeys.isPressed('b'));\n  console.log(hotkeys.isPressed('c'));\n});\n```\n\n## layouts\n\nYou can get the default layouts exported by the library with `Layouts` or create your own one. To change the layout use the `setKeyboardLayout`.\n\n```ts\nimport { hotkeys, Layouts } from 'modern-hotkeys';\n\nhotkeys(...);\n\nhotkeys.setKeyboardLayout(Layouts['es-la']);\n\n\n// or if you have your instance\n\nimport { createHotkeys, Layouts } from 'modern-hotkeys';\n\nconst instance = createHotkeys({ element: document.body });\n\ninstance.hotkeys(...);\ninstance.setKeyboardLayout(Layouts['es-la']);\n```\n\n## unbind\n\nUnbind a shortcut or all shortcuts.\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\n// unbind defined key\nhotkeys.unbind('ctrl + s');\n\n// unbind defined key and scope\nhotkeys.unbind('command + s', 'my-scope-files');\n\n// unbind all\nhotkeys.unbind();\n\n// or if you have your instance\n\nimport { createHotkeys } from 'modern-hotkeys';\n\nconst instance = createHotkeys({ element: document.body });\n\n// unbind defined key\ninstance.unbind('ctrl + s');\n\n// unbind defined key and scope\ninstance.unbind('command + s', 'my-scope-files');\n\n// unbind all\ninstance.unbind();\n```\n\n## setEventFilter\n\nUseful to filter input events and not fire shortcut when the user is writing on an input.\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\n// filter inputs\nhotkeys.setEventFilter((e) =\u003e e.target?.tagName !== 'INPUT');\n\n// allow all events\nhotkeys.setEventFilter(() =\u003e true);\n\n// or if you have your instance\n\nimport { createHotkeys } from 'modern-hotkeys';\n\nconst instance = createHotkeys({ element: document.body });\n\n// filter inputs\ninstance.setEventFilter((e) =\u003e e.target?.tagName !== 'INPUT');\n\n// allow all events\ninstance.setEventFilter(() =\u003e true);\n```\n\n## setVerbose\n\nShow debug logs\n\n```ts\nimport { createHotkeys } from 'modern-hotkeys';\n\nconst instance = createHotkeys({ element: document.body });\n\ninstance.setVerbose(true);\n\ninstance.hotkeys('shift + c', () =\u003e {\n  ...\n});\n```\n\n## stopPropagation\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys(\n  'escape',\n  (e, h) =\u003e {\n    h.stopPropagation();\n    alert('cancelling 1!');\n  },\n  { order: 0 },\n);\n\nhotkeys(\n  'escape',\n  () =\u003e {\n    // it won't be triggered\n    alert('cancelling 2!');\n  },\n  { order: 1 },\n);\n```\n\n## Options\n\nThe third argument of `hotkeys` could be an object with options.\n\n### order\n\nYou can scale the priority of a shortcut using negative numbers.\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys('escape', () =\u003e {\n  alert('cancelling 2!');\n});\n\nhotkeys(\n  'escape',\n  (e, h) =\u003e {\n    alert('cancelling 1!');\n  },\n  { order: -1000 },\n);\n```\n\n### event\n\nYou can define what event will trigger your shortcut\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys(\n  'control + s',\n  () =\u003e {\n    console.log('triggered on keydown');\n  },\n  { event: 'keydown' },\n);\n\nhotkeys(\n  'control + s',\n  () =\u003e {\n    console.log('triggered on keyup');\n  },\n  { event: 'keyup' },\n);\n```\n\n### scope\n\nDefine the scope of the shortcut\n\n```ts\nimport { hotkeys } from 'modern-hotkeys';\n\nhotkeys(\n  'control + s',\n  () =\u003e {\n    console.log('triggered on scope myscope');\n  },\n  { scope: 'myscope' },\n);\n```\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpato12%2Fmodern-hotkeys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpato12%2Fmodern-hotkeys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpato12%2Fmodern-hotkeys/lists"}