How the Gamepad API Works
The Gamepad API gives web pages read access to connected game controllers through navigator.getGamepads(), which returns a snapshot array of every controller the browser currently recognizes. Unlike most browser APIs, it's not event-driven for input - there's no "button pressed" callback. Instead, a page is expected to poll the array on every animation frame using requestAnimationFrame, read the current buttons and axes values, and redraw.
Each gamepad object exposes a buttons array (each with a pressed boolean and a value from 0 to 1, for analog pressure) and an axes array of floating point numbers from -1 to 1 (typically the first two for the left stick's X/Y and the next two for the right stick's X/Y on a standard-mapped controller). This tool polls both, every frame, to render a live view of every input.
Connecting a Controller
For privacy and security reasons, browsers won't reveal that a gamepad is connected until you interact with it - simply plugging in or pairing a controller isn't enough. Press any button, or move a stick, on the controller itself after it's connected at the OS level, and the browser will fire a gamepadconnected event (which this tool listens for) and begin including it in navigator.getGamepads().
If your controller connects over Bluetooth, make sure it's fully paired in your operating system's Bluetooth settings first - the Gamepad API only sees devices your OS has already connected, it cannot pair a new device on its own.
Common Use Cases
How to Read the Layout
| Element | Source | Meaning |
|---|---|---|
| Button grid cell | buttons[i].pressed | Highlights when a button is currently held down |
| Button pressure bar | buttons[i].value | Analog pressure from 0-1, most meaningful on triggers (L2/R2) |
| Stick dot position | axes[0..3] | Left stick X/Y and right stick X/Y, each from -1 to 1, on a standard mapping |
| Connection badge | gamepadconnected / gamepaddisconnected | Fires when a controller is recognized or removed |
On a controller reporting the standard mapping (most Xbox/PlayStation-style pads), button indices follow a consistent order, so this tool labels them with familiar names. Non-standard controllers still work, just with generic "Button N" labels since the physical layout can't be assumed.
Frequently Asked Questions
The spec was designed around game loops. Games already run a per-frame update via requestAnimationFrame, so handing back a fresh array to read on each frame fits naturally and avoids the overhead of dispatching a stream of events for continuously changing analog values like stick position.
It's a spec-defined layout guaranteeing 17 buttons and 4 axes in fixed positions matching a typical Xbox/PlayStation-style controller, so games can rely on consistent indices without per-device configuration. A controller that doesn't match reports an empty mapping string and its own raw button/axis order instead.
Analog stick sensors (potentiometers or Hall-effect modules) have small manufacturing tolerances and can develop drift as they wear, so a resting stick often reports a tiny nonzero value rather than a perfect zero - which is also why tools like this one only flag a stick as "moved" past a small threshold instead of treating any nonzero reading as active input.
Some browsers expose a vibrationActuator on standard-mapped controllers that lets a page trigger haptic feedback, but that's a separate, opt-in output capability - this tool only reads input (buttons, triggers, sticks) and does not use it.
For controllers reporting the standard mapping, yes - indices are consistent by spec. For non-standard controllers, the raw index order comes straight from the OS/driver's HID report layout and can differ between browsers or operating systems, which is why unmapped controllers get generic "Button N" labels instead of guessed names.