Live demo · npm

Virtual multi-touch joysticks, buttons, and D-pads for JavaScript games, apps, and IoT. Works with mouse, pen, and touch. Includes JSDoc types for editor hints and type checking.

Install

npm install @rbuljan/gamepad

Usage

Create a container with a position and height:

<div id="controls" style="position: relative; height: 300px;"></div>

Add your controls. Gamepad initializes them automatically:

import { Gamepad } from "@rbuljan/gamepad";

const gamepad = new Gamepad([
    {
        id: "move",
        type: "joystick",
        parent: "#controls",
        position: { left: "20%", top: "50%" },
        onInput() {
            console.log("Strength:", this.value, "Angle:", this.angle);
        },
    },
    {
        id: "navigate",
        type: "dpad",
        parent: "#controls",
        position: { left: "50%", top: "50%" },
        onInput() {
            console.log("Direction:", this.value ? this.direction : "idle");
        },
    },
    {
        id: "fire",
        type: "button",
        parent: "#controls",
        position: { left: "80%", top: "50%" },
        text: "Fire",
        onInput() {
            if (this.value) console.log("Fire!");
        },
    },
]);

// Read the latest input from your game loop.
console.log(gamepad.controllers.move.value);

Use method syntax for onInput() as shown, so this refers to the controller. It runs when input changes through a press, drag, or release, rather than on every animation frame.

Standalone controls

Each controller also works on its own. These independent examples use the same #controls container; call init() to display the control and destroy() to remove it.

IDs are generated automatically and are available as controller.id. Set id when you want a name for lookup, such as gamepad.controllers.move.

Horizontal joystick

import { Joystick } from "@rbuljan/gamepad";

const joystick = new Joystick({
    parent: "#controls",
    axis: "x",
    onInput() {
        console.log("Rotation:", this.value); // -1 (left) to 1 (right)
    },
});

joystick.init();

Toggle button

import { Button } from "@rbuljan/gamepad";

const button = new Button({
    parent: "#controls",
    text: "Menu",
    spring: false,
    onInput() {
        console.log("Menu open:", Boolean(this.value));
    },
});

button.init();

Horizontal D-pad

import { DPad } from "@rbuljan/gamepad";

const dpad = new DPad({
    parent: "#controls",
    axis: "x",
    onInput() {
        const horizontal = this.value ? (this.direction === 0 ? 1 : -1) : 0;
        console.log("Steering:", horizontal); // -1 left, 0 idle, 1 right
    },
});

dpad.init();

Use axis: "y" for a vertical D-pad (2 down, 6 up), or axis: "all" for all eight directions. Its value is always 0 or 1; check it before reading direction.

Options

Pass these options to Gamepad entries or standalone controllers:

| Option | Default | Description | | --- | --- | --- | | id | Auto-generated | Optional unique controller ID. Omitted or empty IDs are generated once and retained on reinitialization. | | type | "joystick" | "joystick", "button", or "dpad". Standalone classes set this automatically. | | parent | "body" | CSS selector of the container. | | position | { left: "50%", top: "50%" } | CSS position inside the container. | | radius | 50 | Radius in pixels. | | axis | "all" | "all", "x", or "y" for joysticks and D-pads. | | fixed | true | Set to false to reposition a joystick or button where the press starts. D-pads always stay fixed. | | spring | true | Reset input on release. With false, joysticks and D-pads retain input, and buttons toggle on each press. | | deadZone | 0.2 for an all-axis D-pad; otherwise 0 | Inactive fraction of the D-pad radius, from 0 to 1. Applies only to D-pads. | | directionsTot | 8 | Number of direction regions for joysticks and D-pads. | | text | "" | Label or HTML content, typically for buttons. | | style | {} | CSS styles, e.g. { color: "#3498db" }. | | onInput() | No action | Input callback; this is the controller. |

With spring: false, releasing does not call onInput(). For multiple non-fixed controls, use separate positioned containers so their touch areas do not overlap.

Input values

Read these inside onInput() using this, or through gamepad.controllers[id]:

| Property | Meaning | | --- | --- | | value | Joystick: 0 to 1 on all axes, or -1 to 1 on a single axis. Button and D-pad: 0 or 1. | | angle | Joystick/D-pad angle in radians, clockwise from right, from 0 up to (but excluding) 2π. | | direction | Joystick/D-pad direction index, clockwise from right. | | angleDirection | Angle in radians snapped to the current direction. | | isPress | Whether a pointer is currently held down. | | isDrag | Whether a joystick or D-pad has moved during the current press. | | isActive | Active state; for toggle buttons, whether the button is on. |

A single-axis joystick is positive to the right on X and up on Y. With eight directions, direction is:

| Right | Down-right | Down | Down-left | Left | Up-left | Up | Up-right | | --- | --- | --- | --- | --- | --- | --- | --- | | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |

A D-pad has value: 0 inside its dead zone and, with the default spring: true, on release. Its last direction is retained on release.

Methods

new Gamepad([...]) accepts controller options or existing Joystick, Button, and DPad instances. The array is optional.

| Gamepad method | Description | | --- | --- | | add(...controllers) | Add and initialize controller options or instances. | | remove(...idsOrControllers) | Remove and destroy controllers by ID or instance. | | destroy() | Remove all controllers and the fullscreen listener. Pass an ID or instance to remove only that controller. | | requestFullScreen() | Enable fullscreen requests on clicks/taps. | | exitFullScreen() | Exit fullscreen. | | isVibrationSupported() | Return whether browser vibration is supported. | | vibrate(100) | Vibrate for a duration in milliseconds, or pass a pattern such as [100, 30, 100]. |

Gamepad methods return the gamepad for chaining, except isVibrationSupported(), which returns a boolean. Fullscreen and vibration depend on browser support.

Standalone controllers have init() to create their UI and destroy() to remove it and its listeners. To let a gamepad manage them instead, use gamepad.add(controller).

Styling

Use style for individual controls, or CSS for their pressed appearance:

.Gamepad-controller.is-active {
    box-shadow: 0 0 20px currentColor;
}

Development

npm install
npm run dev        # Run the example locally; open the URL printed by Vite
npm run typecheck  # Check library JSDoc types
npm test
npm run build      # Build the library and example
npm run build:pages # Build the GitHub Pages demo

See live demo

License

MIT