{"id":15316446,"url":"https://github.com/doemser/use-wasd","last_synced_at":"2025-06-29T03:41:57.188Z","repository":{"id":59145182,"uuid":"535324241","full_name":"doemser/use-wasd","owner":"doemser","description":"Easy and agnostic react hook to handle keys and key-combinations on your keyboard.","archived":false,"fork":false,"pushed_at":"2022-11-28T00:16:49.000Z","size":2919,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T14:11:09.430Z","etag":null,"topics":["gaming","gaming-website","hook","hooks","keyboard","react","react-hooks","shortcuts"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/use-wasd","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doemser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-11T14:31:51.000Z","updated_at":"2023-06-06T09:33:13.000Z","dependencies_parsed_at":"2023-01-22T17:31:25.184Z","dependency_job_id":null,"html_url":"https://github.com/doemser/use-wasd","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doemser%2Fuse-wasd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doemser%2Fuse-wasd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doemser%2Fuse-wasd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doemser%2Fuse-wasd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doemser","download_url":"https://codeload.github.com/doemser/use-wasd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991709,"owners_count":21194925,"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":["gaming","gaming-website","hook","hooks","keyboard","react","react-hooks","shortcuts"],"created_at":"2024-10-01T08:54:08.593Z","updated_at":"2025-04-15T02:20:43.814Z","avatar_url":"https://github.com/doemser.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://github.com/doemser/dead-simple-react/blob/main/assets/png/use-wasd.png?raw=true\" alt=\"use-wad\"/\u003e\n\n[![Version](https://img.shields.io/npm/v/use-wasd?style=flat\u0026colorA=000000\u0026colorB=000000)](https://www.npmjs.com/package/use-wasd)\n[![Build Size](https://img.shields.io/bundlephobia/minzip/use-wasd?label=bundle%20size\u0026style=flat\u0026colorA=000000\u0026colorB=000000)](\u003c[https://bundlephobia.com/result?p=use-wasd](https://bundlephobia.com/package/use-wasd@2.0.1)\u003e)\n[![Downloads](https://img.shields.io/npm/dt/use-wasd.svg?style=flat\u0026colorA=000000\u0026colorB=000000)](https://www.npmjs.com/package/use-wasd)\n\nEasy and agnostic react hook to handle keys and key-combinations on your keyboard.\n\n```bash\nnpm install use-wasd\n```\n\nThis hook returns an object with the keys and combos and their pressed state.\n\n```js\nimport useWASD from \"use-wasd\";\n\nexport default function App() {\n  const keyboard = useWASD();\n\n  return (\n    \u003cpre\u003e\n      \u003ccode\u003e{JSON.stringify(keyboard)}\u003c/code\u003e\n    \u003c/pre\u003e\n  );\n}\n```\n\n\u003ca href=\"https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-basic\" target=\"_blank\"\u003e![Try it yourself.](https://github.com/doemser/dead-simple-react/blob/main/assets/png/use-wasd-try-it-yourself.png?raw=true)\u003c/a\u003e\n\n---\n\n### Table of Content\n\n- [Options](#options)\n  - [allow/block](#allowblock)\n  - [combos](#combos)\n  - [initialValue](#initialvalue)\n  - [preventDefault](#preventdefault)\n  - [ref](#ref)\n- [Performance](#performance)\n  - [Destructuring](#destructuring)\n  - [Memoization](#memoization)\n- [Examples](#examples)\n- [Learn](#learn)\n\n---\n\n## Options\n\nYou can pass an optional `options` object.\n\n```js\nconst options = { allow: [\"w\", \"a\", \"s\", \"d\"] };\n\nexport default function App() {\n  const { w, a ,s ,d }  = useWASD(options);\n  ...\n}\n```\n\nAvailable options are:\n\n- allow\n- block\n- combos\n- initialValue\n- preventDefault\n- ref\n\n---\n\n### allow/block\n\nYou can and should explicitly allow or block keys.\n\n```js\nconst options = {\n  // either\n  allow: [\"w\", \"shift\", \"c\"],\n  // or\n  block: [\"c\"],\n};\n```\n\n\u003e Do not use both.\n\n---\n\n### combos\n\nYou can define custom combos.\n\n```js\nconst options = {\n  allow: [\"w\", \"shift\", \"space\"],\n  combos: { sprint: [\"w\", \"shift\"], sprintJump: [\"w\", \"shift\", \"space\"] }\n};\n\nexport default function App() {\n  const { sprint, sprintJump } = useWASD(options);\n  ...\n}\n```\n\n\u003e You don´t need to also allow combos, it´s enough if the keys for the combo are allowed and not blocked.\n\n\u003ca href=\"https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-combos\" target=\"_blank\"\u003e![Try it yourself.](https://github.com/doemser/dead-simple-react/blob/main/assets/png/use-wasd-try-it-yourself.png?raw=true)\u003c/a\u003e\n\n---\n\n### initialValue\n\nYou can initially fill the object.\n\n```js\nconst options = {\n  initialValue: { w: true, shift: false, sprint: false },\n};\n```\n\n\u003e Note that the `\"keydown\"` event will always set keys `true`, while the `\"keyup\"` event will always set to `false`. Initially setting a key to `true` will not reverse the mechanism.\n\n\u003ca href=\"https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-initial-value\" target=\"_blank\"\u003e![Try it yourself.](https://github.com/doemser/dead-simple-react/blob/main/assets/png/use-wasd-try-it-yourself.png?raw=true)\u003c/a\u003e\n\n---\n\n### preventDefault\n\nYou can call `event.preventDefault()` to prevent default actions for keys.\n\n```js\nconst options = { preventDefault: [\"arrowup\", \"arrowdown\"] };\n```\n\nYou can also set it to `true` to prevent the default function for every key.\n\n```js\nconst options = { preventDefault: true };\n```\n\n\u003e Be aware that by doing so you can jeopardize the a11y\n\n\u003ca href=\"https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-prevent-default\" target=\"_blank\"\u003e![Try it yourself.](https://github.com/doemser/dead-simple-react/blob/main/assets/png/use-wasd-try-it-yourself.png?raw=true)\u003c/a\u003e\n\n---\n\n### ref\n\nBy default the EventListener will be added to the `document`, if you want it to be added to another element, you can pass it as `ref`.\n\n```js\nexport default function App() {\n  const ref = useRef();\n  const keyboard = useWASD({...options, ref});\n  ...\n}\n```\n\n\u003ca href=\"https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-ref\" target=\"_blank\"\u003e![Try it yourself.](https://github.com/doemser/dead-simple-react/blob/main/assets/png/use-wasd-try-it-yourself.png?raw=true)\u003c/a\u003e\n\n---\n\n## Performance\n\n### Destructuring\n\n\u003e We recommend destructuring the object returned by useWASD.\n\n```diff\n\nexport default function App() {\n-  const keyboard  = useWASD();\n+  const { w, a ,s ,d }  = useWASD();\n  ...\n}\n```\n\n### Memoization\n\n\u003e We recommend memoizing the options object.\n\nHere are 3 common examples of passing the options object:\n\n1. Declare it outside the Component.\n\n```js\nconst options = {...};\n\nexport default function App() {\n  const keyboard = useWASD(options);\n  ...\n}\n```\n\n2. Using useMemo hook.\n\n```js\n\nexport default function App() {\n  const options = useMemo(() =\u003e ({...}), []);\n  const keyboard = useWASD(options);\n  ...\n}\n```\n\n3. Using useRef hook.\n\n```js\n\nexport default function App() {\n  const options = useRef({...});\n  const keyboard  = useWASD(options.current);\n  ...\n}\n```\n\nDo not pass the object directly into the hook, this would cause unnecessary rerenders.\n\n```js\n\nexport default function App() {\n  const keyboard = useWASD({...});\n  ...\n}\n```\n\n---\n\n## Examples\n\n[Basic Example](https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-basic)\n\n[combos Example](https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-combos)\n\n[initialValue Example](https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-initial-value)\n\n[preventDefault Example](https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-prevent-default)\n\n[ref Example](https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-ref)\n\n---\n\n## Learn\n\n[useWASD vanilla source](https://codesandbox.io/s/github/doemser/dead-simple-react/tree/main/examples/use-wasd/use-wasd-vanilla)\n\n\u003e if you are familiar with typescript, you can also find the source code on [github](https://github.com/doemser/use-wasd/blob/main/src/use-wasd.ts).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoemser%2Fuse-wasd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoemser%2Fuse-wasd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoemser%2Fuse-wasd/lists"}