{"id":18447506,"url":"https://github.com/cyrus2281/joystick-controller","last_synced_at":"2025-08-20T20:32:29.433Z","repository":{"id":65201702,"uuid":"587104016","full_name":"cyrus2281/joystick-controller","owner":"cyrus2281","description":"A JavaScript virtual joystick controller for both desktop and mobile devices.","archived":false,"fork":false,"pushed_at":"2024-08-27T02:22:22.000Z","size":1561,"stargazers_count":22,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-06T11:45:54.141Z","etag":null,"topics":["controller","gamepad","joystick","joystick-controller","touch-control","touch-joystick","touchpad"],"latest_commit_sha":null,"homepage":"https://joystick-controller.netlify.app","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/cyrus2281.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":"2023-01-10T00:53:06.000Z","updated_at":"2024-12-01T05:38:41.000Z","dependencies_parsed_at":"2024-08-27T02:26:52.727Z","dependency_job_id":"5dd7a590-57fb-4fac-a3f2-8cb7e66432dc","html_url":"https://github.com/cyrus2281/joystick-controller","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus2281%2Fjoystick-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus2281%2Fjoystick-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus2281%2Fjoystick-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus2281%2Fjoystick-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyrus2281","download_url":"https://codeload.github.com/cyrus2281/joystick-controller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230454428,"owners_count":18228392,"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":["controller","gamepad","joystick","joystick-controller","touch-control","touch-joystick","touchpad"],"created_at":"2024-11-06T07:13:30.672Z","updated_at":"2024-12-19T15:08:46.143Z","avatar_url":"https://github.com/cyrus2281.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/cyrus2281"],"categories":[],"sub_categories":[],"readme":"# Joystick Controller\n\n[![npm](https://img.shields.io/npm/v/joystick-controller)](https://www.npmjs.com/package/joystick-controller)\n[![GitHub](https://img.shields.io/github/package-json/v/cyrus2281/joystick-controller?color=red\u0026label=Github)](https://github.com/cyrus2281/joystick-controller)\n[![License](https://img.shields.io/github/license/cyrus2281/joystick-controller)](https://github.com/cyrus2281/joystick-controller/blob/main/LICENSE)\n[![buyMeACoffee](https://img.shields.io/badge/BuyMeACoffee-cyrus2281-yellow?logo=buymeacoffee)](https://www.buymeacoffee.com/cyrus2281)\n\n![joystick-controller](https://raw.githubusercontent.com/cyrus2281/joystick-controller/main/example/joystick-controller.gif)\n\nA fully customizable JavaScript virtual joystick controller for both desktop and mobile devices supporting multi instances.\n[Live Demo](https://joystick-controller.netlify.app)\n\n## Installation\n\n```bash\nnpm install joystick-controller\n```\n\n## Quick Start\n\n```js\nimport JoystickController from \"joystick-controller\";\n\nconst joystick = new JoystickController({}, (data) =\u003e console.log(data));\n```\n\nThe import example here is module style import. JoystickController also supports global and commonJs import style.\n\n## Options\n\nYou can pass a set of options as the first argument to further customize your joystick controller\n\n| Name                  | Type           | Default    | Description                                                                                                                                        |\n| --------------------- | -------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |\n| maxRange              | number         | 100        | Maximum range of the joystick dot (number of pixels)                                                                                               |\n| level                 | number         | 10         | Number of level of the joystick (eg 10 would return integers between -10 and 10)                                                                   |\n| radius                | number         | 50         | Radius of the joystick container (number of pixels)                                                                                                |\n| joystickRadius        | 30             | number     | Radius of the joystick inner dot (number of pixels)                                                                                                |\n| opacity               | number         | 0.8        | Opacity of the joystick                                                                                                                            |\n| containerClass        | string         | ''         | Class for the joystick container for adding additional styles (outer container)                                                                    |\n| controllerClass       | string         | ''         | Class for the joystick controller for adding additional styles (inner container)                                                                   |\n| joystickClass         | string         | ''         | Class for the joystick dot for adding additional styles                                                                                            |\n| leftToRight           | boolean        | true       | Left to right adjustment (x position from left)(ignored if dynamicPosition=true)                                                                   |\n| bottomToUp            | boolean        | true       | Bottom to up adjustment (y position from bottom)(ignored if dynamicPosition=true)                                                                  |\n| x                     | string         | '50%'      | x position of the joystick controller on screen (equal to left/right of css)(ignored if dynamicPosition=true)                                      |\n| y                     | string         | '50%'      | y position of the joystick controller on screen (equal to bottom/top of css)(ignored if dynamicPosition=true)                                      |\n| distortion            | boolean        | false      | if true, the joystick will be distorted when the dot is moved to the edge of the joystick                                                          |\n| dynamicPosition       | boolean        | false      | Shows the joystick when the user touch/click on the screen at the position where it was clicked/touched                                            |\n| dynamicPositionTarget | HTMLElement    | null       | If dynamicPosition true, uses this target to set the event listener on (if not provided use document)                                              |\n| mouseClickButton      | string\\|number | \"ALL\" (-1) | click button to show the joystick (if not provided, shows on all clicks)(Values: ALL, LEFT, MIDDLE, RIGHT, or button number (-1 to 4. -1 for all)) |\n| hideContextMenu       | boolean        | false      | if true, hides the context menu on right click  (Recommended to be used dynamicPosition and dynamicPositionTarget) |\n\n## Callback Arguments\n\nJoystick would trigger the callback on each move event. The following arguments are passed to the callback.\n| Name | Type | Description |\n| ------------- | ------------- | ------------- |\n| x | number | x position of the joystick relative to the center of it\n| y | number | y position of the joystick relative to the center of it\n| leveledX | number | x position scaled and rounded to be a step between -level to level (level comes from options)\n| leveledY | number | y position scaled and rounded to be a step between -level to level (level comes from options)\n| angle | number | angle of the line between center of the joystick and position of the dot in radians\n| distance | number | distance of the dot from the center joystick\n\n## Customized Example\n\nAll the options are optional, but a customized instance would look like this:\n\n```js\n// Static Example\nconst staticJoystick = new JoystickController(\n  {\n    maxRange: 70,\n    level: 10,\n    radius: 50,\n    joystickRadius: 30,\n    opacity: 0.5,\n    leftToRight: false,\n    bottomToUp: true,\n    containerClass: \"joystick-container\",\n    controllerClass: \"joystick-controller\",\n    joystickClass: \"joystick\",\n    distortion: true,\n    x: \"25%\",\n    y: \"25%\",\n    mouseClickButton: \"ALL\",\n    hideContextMenu: false,\n  },\n  ({ x, y, leveledX, leveledY, distance, angle }) =\u003e\n    console.log(x, y, leveledX, leveledY, distance, angle)\n);\n// Dynamic Position Example\nconst dynamicJoystick = new JoystickController(\n  {\n    maxRange: 70,\n    level: 10,\n    radius: 50,\n    joystickRadius: 30,\n    opacity: 0.5,\n    containerClass: \"joystick-container\",\n    controllerClass: \"joystick-controller\",\n    joystickClass: \"joystick\",\n    distortion: true,\n    dynamicPosition: true,\n    dynamicPositionTarget: document.getElementById(\"root\"),\n    mouseClickButton: \"ALL\",\n    hideContextMenu: true,\n  },\n  ({ x, y, leveledX, leveledY, distance, angle }) =\u003e\n    console.log(x, y, leveledX, leveledY, distance, angle)\n);\n```\n\n## Clean Up\n\nRun `destroy` function to clear all the event listeners and remove the joystick from the document\n\n```js\njoystick.destroy();\n```\n\n---\n\nCopyright(c) Cyrus Mobini 2024\n\nLicense MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus2281%2Fjoystick-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrus2281%2Fjoystick-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus2281%2Fjoystick-controller/lists"}