Gamepad & Controller Tester

The Complete Gamepad Tester Guide

How the browser Gamepad API reads controller input, why a button press is needed to connect, and how to read the button and stick layout.

Open Gamepad Tester

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

Diagnose Stick DriftWatch the dot on the stick pad while your hands are off the controller - it should sit dead center.
Check Every ButtonPress each face button, bumper, trigger, and D-pad direction and confirm it registers immediately.
Web Game DevelopmentDevelopers can confirm exactly what button/axis indices a given controller reports before wiring up in-game controls.

How to Read the Layout

ElementSourceMeaning
Button grid cellbuttons[i].pressedHighlights when a button is currently held down
Button pressure barbuttons[i].valueAnalog pressure from 0-1, most meaningful on triggers (L2/R2)
Stick dot positionaxes[0..3]Left stick X/Y and right stick X/Y, each from -1 to 1, on a standard mapping
Connection badgegamepadconnected / gamepaddisconnectedFires 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

Why is the Gamepad API a polling snapshot instead of firing button-press events?

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.

What does the "standard" gamepad mapping actually guarantee?

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.

Why don't stick axis values sit at exactly 0.00 when idle?

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.

Can the Gamepad API detect or trigger a controller's rumble motors?

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.

Does a controller's button index order stay the same across different browsers?

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.

Open Gamepad Tester