The browser Gamepad API is how a web-based gamepad tester reads your controller. Pages poll navigator.getGamepads(), listen for connect and disconnect events, and display buttons, axes, mapping strings, and sometimes a vibration actuator. The API does not invent devices. It only exposes pads the operating system already accepts. That design keeps the web safe, but it also means browser tools inherit OS and browser limits.
What the API can do
- Detect connected pads after a user gesture such as a button press.
- Report live button pressed states and analog values for sticks and triggers.
- Expose a mapping hint (often standard for Xbox-style layouts).
- Optionally send dual-rumble when
vibrationActuatorexists and the browser allows it.
Those capabilities are enough for practical diagnostics on the Controller Tester, Stick Drift, Deadzone, Vibration, and Controller Detection pages. Developers inspecting raw snapshots can also use specialized debugger views on this site.
What the API cannot do
- Call native Windows XInput directly from ordinary web pages.
- Write DualSense NVS or permanent firmware calibration without specialized WebHID or vendor tools.
- Guarantee adaptive triggers, touchpad gestures, gyro fusion, or vendor-only haptics.
- Promise identical behavior on every mobile browser.
Missing rumble in Chromium over Bluetooth does not always mean dead motors. Missing adaptive trigger resistance in a browser does not mean the DualSense is broken. Be honest about the layer you are testing: the Gamepad API is a compatibility window, not a full console SDK.
How this site uses the API
Gamepad Tester pages poll gamepads on animation frames, normalize common layouts when mapping is standard, and visualize axes for stick drift and deadzone education. They do not claim to flash firmware. When a pad is absent, follow Controller Not Detected. For Windows connection choices, see Controller on PC and the PC Controller Tester. Drift and deadzone guides explain hardware versus settings: How to Fix Stick Drift and Deadzone Explained.
If you are learning the stack, start with detection, then buttons, then axes, then optional vibration. Read more walkthroughs on the blog and keep expectations matched to what a browser can see. A clear mental model of the Gamepad API turns a gamepad tester from a mystery box into a trustworthy diagnostic tool.
Events and polling: how the browser watches your pad
The Gamepad API does not stream controllers to a page on its own. A page asks for the current snapshot by calling navigator.getGamepads(), which returns a list of up to four pads — the same four slots you see on the Controller Tester. The browser also fires connect and disconnect events when a pad appears or leaves, and tester pages re-read the snapshot on every animation frame so buttons, sticks, and triggers update live. Two consequences follow. First, a pad that falls asleep or unplugs simply vanishes from the next snapshot — that is normal, not a crash. Second, browsers require a button press before they expose a pad at all: this user-gesture rule exists for privacy, so a page cannot silently fingerprint your hardware. A connected but never-pressed controller staying invisible is the API working as designed, not a bug.
Mapping: standard versus unknown
Every pad carries a mapping string. When it reads "standard", the layout follows the familiar Xbox-style arrangement: known button indexes for face buttons, bumpers, triggers, and sticks, and known axis pairs. When it reads empty or unknown, the browser is telling you the operating system and driver did not supply a standard layout — common for generic DirectInput pads, arcade sticks, and some Bluetooth modes. Unknown mapping is not a fault: the pad still reports every control, but you must learn its indexes by pressing each control once on the Controller Button Test and writing down what lights up. The same physical pad can even show different labels in different browsers, because mapping comes from the OS and driver stack, not from the pad alone. Trust the indexes you measure in the browser you are using, not the names printed on the shell.
Buttons and axes, up close
Under the snapshot, a gamepad is two lists. The buttons list reports each control three ways: pressed (true or false), touched (for touch-sensitive surfaces), and value — a number from 0 to 1 that makes triggers analog instead of on-off. The axes list reports sticks as pairs of floating numbers from -1 to 1, left-right and up-down per stick. Triggers often appear twice: once as buttons (usually indexes 6 and 7) with analog values, and sometimes as axes too. Each snapshot also carries a timestamp so a page can tell fresh data from a stale frame. When a tester shows a button stuck at 0.50 or an axis parked off-center, it is reporting exactly what the OS handed the browser — the tester is the messenger, and the fault lives upstream in the pad, cable, mode, or driver.
The vibration actuator, honestly
Rumble through the Gamepad API is deliberately narrow: a dual-rumble effect with weak and strong motors, where the browser allows it at all. Chromium-based browsers offer the best support, Firefox is partial, and Safari is the weakest — and all of them require a secure HTTPS page before vibration is available. What the API cannot do matters just as much: no adaptive trigger resistance, no touchpad gestures, no gyro fusion, and no vendor-only haptics. So a DualSense that rumbles beautifully in a native game but only pulses weakly in the Vibration Test is not broken — the browser is using the one narrow channel the standard provides, while the game uses private channels the web cannot reach.
Gamepad API versus WebHID
If the Gamepad API is a read-only window, WebHID is a gated door. WebHID lets a page talk to a USB device more deeply, but only after the user explicitly grants permission for that device, and only over USB in supporting Chromium browsers. That is why the PS4 / PS5 Calibration tool is a separate, deeper layer from the standard tester: permanent stick center and range writes need device-level access the Gamepad API will never provide. Vendor firmware tools sit one layer further still — they alone can update firmware and rewrite device memory. The honest mental model is three layers: the Gamepad API for diagnosis, WebHID for permitted device access, and vendor tools for firmware. A browser tester that claims to do all three from one page is overselling.
Frequently asked questions
Is the Gamepad API safe?
Yes. It is read-only apart from short rumble pulses: a page can see buttons, axes, and mapping, but it cannot install anything, change settings, or rewrite firmware. The button-press requirement exists precisely so pages cannot silently enumerate your hardware.
Why does the browser need HTTPS for gamepads?
Device APIs live behind secure contexts. An HTTPS page proves its identity before the browser hands it hardware data or vibration access; an insecure page gets nothing. This is a browser rule, not a limitation of any tester site.
Can a website control my controller?
Only in one narrow way: it can request short rumble pulses through the vibration actuator where supported. It cannot remap buttons, change calibration, update firmware, or send any other command to the pad.
Why do button numbers differ between browsers?
Because mapping and indexes come from the operating system and driver stack, which differ across browsers and platforms. Measure indexes fresh in the browser session you are testing in, and map by those indexes rather than by printed button names.