{"id":13393475,"url":"https://github.com/ianstormtaylor/is-hotkey","last_synced_at":"2025-04-14T23:32:23.915Z","repository":{"id":48834580,"uuid":"107062480","full_name":"ianstormtaylor/is-hotkey","owner":"ianstormtaylor","description":"Check whether a browser event matches a hotkey.","archived":false,"fork":false,"pushed_at":"2023-04-05T10:32:50.000Z","size":126,"stargazers_count":352,"open_issues_count":15,"forks_count":23,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-30T01:57:22.184Z","etag":null,"topics":["browser","events","hotkeys","javascript","keyboard"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/ianstormtaylor.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-16T01:10:04.000Z","updated_at":"2024-05-11T05:43:09.000Z","dependencies_parsed_at":"2024-01-13T17:11:02.567Z","dependency_job_id":"435b756c-7b0b-4ed7-9663-175ac53fe277","html_url":"https://github.com/ianstormtaylor/is-hotkey","commit_stats":{"total_commits":50,"total_committers":8,"mean_commits":6.25,"dds":0.36,"last_synced_commit":"730069441246b765d6a06189d0a5f58c8c598ab9"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fis-hotkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fis-hotkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fis-hotkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fis-hotkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ianstormtaylor","download_url":"https://codeload.github.com/ianstormtaylor/is-hotkey/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248978506,"owners_count":21192804,"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":["browser","events","hotkeys","javascript","keyboard"],"created_at":"2024-07-30T17:00:53.800Z","updated_at":"2025-04-14T23:32:23.887Z","avatar_url":"https://github.com/ianstormtaylor.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\n### `is-hotkey`\n\nA simple way to check whether a browser event matches a hotkey.\n\n\u003cbr/\u003e\n\n### Features\n\n- Uses a simple, natural syntax for expressing hotkeys—`mod+s`, `cmd+alt+space`, etc.\n- Accepts `mod` for the classic \"`cmd` on Mac, `ctrl` on Windows\" use case.\n- Can use either `event.which` (default) or `event.key` to work regardless of keyboard layout.\n- Can be curried to reduce parsing and increase performance when needed.\n- Is very lightweight, weighing in at `\u003c 1kb` minified and gzipped.\n\n\u003cbr/\u003e\n\n### Example\n\nThe most basic usage...\n\n```js\nimport isHotkey from 'is-hotkey'\n\nfunction onKeyDown(e) {\n  if (isHotkey('mod+s', e)) {\n    ...\n  }\n}\n```\n\nOr, you can curry the hotkey string for better performance, since it is only parsed once...\n\n```js\nimport isHotkey from 'is-hotkey'\n\nconst isSaveHotkey = isHotkey('mod+s')\n\nfunction onKeyDown(e) {\n  if (isSaveHotkey(e)) {\n    ...\n  }\n}\n```\n\nFor multiple keys, you can pass an array instead:\n\n```js\n\nimport isHotkey from 'is-hotkey'\n\nfunction onKeyDown(e) {\n  if (isHotkey(['delete', 'backspace'], e)) {\n    ...\n  }\n}\n```\n\nYou can also use optional modifiers by adding `?` at the end of them.\nFor instance, here `isHotKey` will return `true` for both: `mod+shift+left` and `shift+left`:\n\n```js\n\nimport isHotkey from 'is-hotkey'\n\nfunction onKeyDown(e) {\n  if (isHotkey('mod?+shift+left', e)) {\n    ...\n  }\n}\n```\n\nThat's it!\n\n\u003cbr/\u003e\n\n### Why?\n\nThere are tons of hotkey libraries, but they're often coupled to the view layer, or they bind events globally, or all kinds of weird things. You don't really want them to bind the events for you, you can do that yourself. \n\nInstead, you want to just check whether a single event matches a hotkey. And you want to define your hotkeys in the standard-but-non-trivial-to-parse syntax that everyone knows.\n\nBut most libraries don't expose their parsing logic. And even for the ones that do expose their hotkey parsing logic, pulling in an entire library just to check a hotkey string is overkill.\n\nSo... this is a simple and lightweight hotkey checker!\n\n\u003cbr/\u003e\n\n### API\n\n```js\nimport isHotkey from 'is-hotkey'\n\nisHotkey('mod+s')(event)\nisHotkey('mod+s', { byKey: true })(event)\n\nisHotkey('mod+s', event)\nisHotkey('mod+s', { byKey: true }, event)\n```\n\nYou can either pass `hotkey, [options], event` in which case the hotkey will be parsed and compared immediately. Or you can passed just `hotkey, [options]` to receive a curried checking function that you can re-use for multiple events.\n\n```js\nisHotkey('mod+a')\nisHotkey('Control+S')\nisHotkey('cmd+opt+d')\nisHotkey('Meta+DownArrow')\nisHotkey('cmd+down')\n```\n\nThe API is case-insentive, and has all of the conveniences you'd expect—`cmd` vs. `Meta`, `opt` vs. `Alt`, `down` vs. `DownArrow`, etc. \n\nIt also accepts `mod` for the classic \"`cmd` on Mac, `ctrl` on Windows\" use case.\n\n```js\nimport isHotkey from 'is-hotkey'\nimport { isCodeHotkey, isKeyHotkey } from 'is-hotkey'\n\nisHotkey('mod+s')(event)\nisHotkey('mod+s', { byKey: true })(event)\n\nisCodeHotkey('mod+s', event)\nisKeyHotkey('mod+s', event)\n```\n\nBy default the hotkey string is checked using `event.which`. But you can also pass in `byKey: true` to compare using the [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) API, which stays the same regardless of keyboard layout.\n\nOr to reduce the noise if you are defining lots of hotkeys, you can use the `isCodeHotkey` and `isKeyHotkey` helpers that are exported.\n\n```js\nimport { toKeyName, toKeyCode } from 'is-hotkey'\n\ntoKeyName('cmd') // \"meta\"\ntoKeyName('a') // \"a\"\n\ntoKeyCode('shift') // 16\ntoKeyCode('a') // 65\n```\n\nYou can also use the exposed `toKeyName` and `toKeyCode` helpers, in case you want to add the same level of convenience to your own APIs.\n\n```js\nimport { parseHotkey, compareHotkey } from 'is-hotkey'\n\nconst hotkey = parseHotkey('mod+s', { byKey: true })\nconst passes = compareHotkey(hotkey, event)\n```\n\nYou can also go even more low-level with the exposed `parseHotkey` and `compareHotkey` functions, which are what the default `isHotkey` export uses under the covers, in case you have more advanced needs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianstormtaylor%2Fis-hotkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianstormtaylor%2Fis-hotkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianstormtaylor%2Fis-hotkey/lists"}