{"id":13495187,"url":"https://github.com/jamiebuilds/tinykeys","last_synced_at":"2025-05-12T15:33:53.879Z","repository":{"id":36985887,"uuid":"283037179","full_name":"jamiebuilds/tinykeys","owner":"jamiebuilds","description":"A tiny (~650 B) \u0026 modern library for keybindings.","archived":false,"fork":false,"pushed_at":"2024-08-20T23:22:32.000Z","size":1177,"stargazers_count":3867,"open_issues_count":30,"forks_count":80,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-05-09T22:26:56.234Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://jamiebuilds.github.io/tinykeys/","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/jamiebuilds.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":"2020-07-27T23:02:08.000Z","updated_at":"2025-05-07T20:42:21.000Z","dependencies_parsed_at":"2024-01-06T23:58:50.996Z","dependency_job_id":"5ea4c0fc-b260-47eb-a3e4-14cb2b39f43f","html_url":"https://github.com/jamiebuilds/tinykeys","commit_stats":{"total_commits":102,"total_committers":16,"mean_commits":6.375,"dds":"0.48039215686274506","last_synced_commit":"fcf253635231925d660fd6699c9a783ecd038faf"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Ftinykeys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Ftinykeys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Ftinykeys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Ftinykeys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamiebuilds","download_url":"https://codeload.github.com/jamiebuilds/tinykeys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253766205,"owners_count":21960866,"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":[],"created_at":"2024-07-31T19:01:32.243Z","updated_at":"2025-05-12T15:33:53.817Z","avatar_url":"https://github.com/jamiebuilds.png","language":"TypeScript","readme":"# `tinykeys`\n\n\u003e A tiny (~650 B) \u0026 modern library for keybindings.\n\u003e [See Demo](https://jamiebuilds.github.io/tinykeys/)\n\n## Install\n\n```sh\nnpm install --save tinykeys\n```\n\nOr for a CDN version, you can use it on [unpkg.com](https://unpkg.com/tinykeys)\n\n## Usage\n\n```js\nimport { tinykeys } from \"tinykeys\" // Or `window.tinykeys` using the CDN version\n\ntinykeys(window, {\n  \"Shift+D\": () =\u003e {\n    alert(\"The 'Shift' and 'd' keys were pressed at the same time\")\n  },\n  \"y e e t\": () =\u003e {\n    alert(\"The keys 'y', 'e', 'e', and 't' were pressed in order\")\n  },\n  \"$mod+([0-9])\": event =\u003e {\n    event.preventDefault()\n    alert(`Either 'Control+${event.key}' or 'Meta+${event.key}' were pressed`)\n  },\n})\n```\n\nAlternatively, if you want to only create the keybinding handler, and register\nit as an event listener yourself:\n\n```js\nimport { createKeybindingsHandler } from \"tinykeys\"\n\nlet handler = createKeybindingsHandler({\n  \"Shift+D\": () =\u003e {\n    alert(\"The 'Shift' and 'd' keys were pressed at the same time\")\n  },\n  \"y e e t\": () =\u003e {\n    alert(\"The keys 'y', 'e', 'e', and 't' were pressed in order\")\n  },\n  \"$mod+KeyD\": event =\u003e {\n    event.preventDefault()\n    alert(\"Either 'Control+d' or 'Meta+d' were pressed\")\n  },\n})\n\nwindow.addEventListener(\"keydown\", handler)\n```\n\n### React Hooks Example\n\nIf you're using tinykeys within a component, you should also make use of the\nreturned `unsubscribe()` function.\n\n```js\nimport { useEffect } from \"react\"\nimport { tinykeys } from \"tinykeys\"\n\nfunction useKeyboardShortcuts() {\n  useEffect(() =\u003e {\n    let unsubscribe = tinykeys(window, {\n      // ...\n    })\n    return () =\u003e {\n      unsubscribe()\n    }\n  })\n}\n```\n\n## Commonly used `key`'s and `code`'s\n\nKeybindings will be matched against\n[`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)\nand[`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values)\nwhich may have some names you don't expect.\n\n| Windows       | macOS           | `key`         | `code`                         |\n| ------------- | --------------- | ------------- | ------------------------------ |\n| N/A           | `Command` / `⌘` | `Meta`        | `MetaLeft` / `MetaRight`       |\n| `Alt`         | `Option` / `⌥`  | `Alt`         | `AltLeft` / `AltRight`         |\n| `Control`     | `Control` / `^` | `Control`     | `ControlLeft` / `ControlRight` |\n| `Shift`       | `Shift`         | `Shift`       | `ShiftLeft` / `ShiftRight`     |\n| `Space`       | `Space`         | N/A           | `Space`                        |\n| `Enter`       | `Return`        | `Enter`       | `Enter`                        |\n| `Esc`         | `Esc`           | `Escape`      | `Escape`                       |\n| `1`, `2`, etc | `1`, `2`, etc   | `1`, `2`, etc | `Digit1`, `Digit2`, etc        |\n| `a`, `b`, etc | `a`, `b`, etc   | `a`, `b`, etc | `KeyA`, `KeyB`, etc            |\n| `-`           | `-`             | `-`           | `Minus`                        |\n| `=`           | `=`             | `=`           | `Equal`                        |\n| `+`           | `+`             | `+`           | `Equal`\\*                      |\n\nSomething missing? Check out the key logger on the\n[demo website](https://jamiebuilds.github.io/tinykeys/)\n\n\u003e _\\* Some keys will have the same code as others because they appear on the\n\u003e same key on the keyboard. Keep in mind how this is affected by international\n\u003e keyboards which may have different layouts._\n\n## Key aliases\n\nIn some instances, tinykeys will alias keys depending on the platform to\nsimplify cross-platform keybindings on international keyboards.\n\n### `AltGraph` (modifier)\n\nOn Windows, on many non-US standard keyboard layouts, there is a key named\n`Alt Gr` or `AltGraph` in the browser, in some browsers, pressing `Control+Alt`\nwill report `AltGraph` as being pressed instead.\n\nSimilarly on macOS, the `Alt` (`Option`) key will sometimes be reported as the\n`AltGraph` key.\n\n**Note:** The purpose of the `Alt Gr` key is to type \"Alternate Graphics\" so you\nwill often want to use the `event.code` (`KeyS`) for letters instead of\n`event.key` (`S`)\n\n```js\ntinykeys(window, {\n  \"Control+Alt+KeyS\": event =\u003e {\n    // macOS: `Control+Alt+S` or `Control+AltGraph+S`\n    // Windows: `Control+Alt+S` or `Control+AltGraph+S` or `AltGraph+S`\n  },\n  \"$mod+Alt+KeyS\": event =\u003e {\n    // macOS: `Meta+Alt+S` or `Meta+AltGraph+S`\n    // Windows: `Control+Alt+S` or `Control+AltGraph+S` or `AltGraph+S`\n  },\n})\n```\n\n## Keybinding Syntax\n\nKeybindings are made up of a **_sequence_** of **_presses_**.\n\nA **_press_** can be as simple as a single **_key_** which matches against\n[`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values)\nand\n[`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)\n(case-insensitive).\n\n```js\n// Matches `event.key`:\n\"d\"\n// Matches: `event.code`:\n\"KeyD\"\n```\n\nPresses can optionally be prefixed with **_modifiers_** which match against any\nvalid value to\n[`KeyboardEvent.getModifierState()`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState).\n\n```js\n\"Control+d\"\n\"Meta+d\"\n\"Shift+D\"\n\"Alt+KeyD\"\n\"Meta+Shift+D\"\n```\n\nThere is also a special `$mod` modifier that makes it easy to support cross\nplatform keybindings:\n\n- Mac: `$mod` = `Meta` (⌘)\n- Windows/Linux: `$mod` = `Control`\n\n```js\n\"$mod+D\" // Meta/Control+D\n\"$mod+Shift+D\" // Meta/Control+Shift+D\n```\n\nAlternatively, you can use parenthesis to use case-sensitive regular expressions\nto match multiple keys.\n\n```js\n\"$mod+([0-9])\" // $mod+0, $mod+1, $mod+2, etc...\n// equivalent regex: /^[0-9]$/\n```\n\n### Keybinding Sequences\n\nKeybindings can also consist of several key presses in a row:\n\n```js\n\"g i\" // i.e. \"Go to Inbox\"\n\"g a\" // i.e. \"Go to Archive\"\n\"ArrowUp ArrowUp ArrowDown ArrowDown ArrowLeft ArrowRight ArrowLeft ArrowRight B A\"\n```\n\nEach press can optionally be prefixed with modifier keys:\n\n```js\n\"$mod+K $mod+1\" // i.e. \"Toggle Level 1\"\n\"$mod+K $mod+2\" // i.e. \"Toggle Level 2\"\n\"$mod+K $mod+3\" // i.e. \"Toggle Level 3\"\n```\n\nEach press in the sequence must be pressed within 1000ms of the last.\n\n### Display the keyboard sequence\n\nYou can use the `parseKeybinding` method to get a structured representation of a\nkeyboard shortcut. It can be useful when you want to display it in a fancier way\nthan a plain string.\n\n```js\nimport { parseKeybinding } from \"tinykeys\"\n\nlet parsedShortcut = parseKeybinding(\"$mod+Shift+K $mod+1\")\n```\n\nResults into:\n\n\u003c!-- prettier-ignore --\u003e\n```js\n[\n  [[\"Meta\", \"Shift\"], \"K\"],\n  [[\"Meta\"], \"1\"],\n]\n```\n\n## Additional Configuration Options\n\nYou can configure the behavior of tinykeys in a couple ways using a third\n`options` parameter.\n\n```js\ntinykeys(\n  window,\n  {\n    M: toggleMute,\n  },\n  {\n    event: \"keyup\",\n    capture: true,\n  },\n)\n```\n\n### `options.event`\n\nValid values: `\"keydown\"`, `\"keyup\"`\n\nKey presses will listen to this event (default: `\"keydown\"`).\n\n\u003e **Note:** Do not pass `\"keypress\"`, it is deprecated in browsers.\n\n### `options.timeout`\n\nKeybinding sequences will wait this long between key presses before cancelling\n(default: `1000`).\n\n\u003e **Note:** Setting this value too low (i.e. `300`) will be too fast for many of\n\u003e your users.\n","funding_links":[],"categories":["TypeScript","🚈 Event handling","others","Framework agnostic packages","JS/TS Utilities",":books: Libraries","Uncategorized","HTML"],"sub_categories":["General utilities","Admin Template \u0026 Component Library","Browser","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamiebuilds%2Ftinykeys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamiebuilds%2Ftinykeys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamiebuilds%2Ftinykeys/lists"}