navigator.getGamepads() is the snapshot entry point to the Gamepad API. Learn the returned array (including null slots), gamepadconnected, reading buttons and axes, five examples, and try-it labs.
Method
Gamepad[] (may include null)
Baseline Widely available
Gamepad API
gamepadconnected
buttons · axes
Controllers, joysticks, and many gamepads can talk to the browser through the Gamepad API. navigator.getGamepads() returns the current snapshot of connected pads.
It is not a live stream by itself. Games usually listen for connect/disconnect events, then poll getGamepads() inside a requestAnimationFrame loop to read buttons and sticks.
On many browsers the pad list stays empty until the user presses a button on the controller. That is normal — listen for gamepadconnected.
getGamepads() Methodnavigator.getGamepads().Gamepad or null.null holes keep other pads at the same index after disconnect.id, index, buttons, axes, connected, mapping, timestamp.window gamepadconnected (and gamepaddisconnected).SecurityError if blocked.General form of the method:
navigator.getGamepads()Array of Gamepad objects (may be empty; entries may be null).// MDN: use connect event, then read by index
window.addEventListener("gamepadconnected", (e) => {
const gp = navigator.getGamepads()[e.gamepad.index];
console.log(
`Gamepad connected at index ${gp.index}: ${gp.id} with ${gp.buttons.length} buttons, ${gp.axes.length} axes.`
);
});
// Skip null slots when listing pads
function listConnectedPads() {
return Array.from(navigator.getGamepads()).filter(Boolean);
}| Goal | Code |
|---|---|
| Feature detect | typeof navigator.getGamepads === "function" |
| Snapshot | navigator.getGamepads() |
| Non-null pads | Array.from(navigator.getGamepads()).filter(Boolean) |
| On connect | window.addEventListener("gamepadconnected", …) |
| First button pressed? | gp.buttons[0].pressed |
| Left stick X | gp.axes[0] (typical) |
Four facts to remember about navigator.getGamepads().
ArrayGamepad or null
WidelySince Mar 2017
Press buttonThen connected event
Poll rAFEach animation frame
| Connect / disconnect events | getGamepads() polling | |
|---|---|---|
| Purpose | Know when pads appear / leave | Read live button & axis state |
| How often | On plug / unplug (after gesture) | Every frame in a game loop |
| Typical use | Log pad id, enable controls UI | Move character, fire, aim |
| Together? | Yes — events for lifecycle, polling for input | |
Examples follow MDN Gamepad API patterns. Prefer Try It Yourself — without a controller (and a button press) the list is often empty.
Detect the API and list non-null gamepads.
Check whether getGamepads exists before using the Gamepad API.
const lines = [
"getGamepads: " +
(typeof navigator.getGamepads === "function" ? "available" : "missing"),
"slots: " +
(typeof navigator.getGamepads === "function"
? navigator.getGamepads().length
: "n/a")
];
console.log(lines.join("\n"));Baseline support is excellent; empty slots usually mean “no activated pad yet.”
null)Filter out empty index holes before displaying controllers.
function listConnectedPads() {
if (!navigator.getGamepads) return ["getGamepads not supported"];
const pads = Array.from(navigator.getGamepads()).filter(Boolean);
if (!pads.length) return ["No active gamepads (press a button on your controller)"];
return pads.map(
(gp) =>
"#" + gp.index + " " + gp.id +
" | buttons=" + gp.buttons.length +
" axes=" + gp.axes.length
);
}
console.log(listConnectedPads().join("\n"));filter(Boolean) drops null slots so UI lists stay clean.
Handle connect events, read buttons, and poll in a game loop.
gamepadconnected (MDN)MDN pattern: on connect, re-read the pad from getGamepads() by index.
window.addEventListener("gamepadconnected", (e) => {
const gp = navigator.getGamepads()[e.gamepad.index];
console.log(
"Gamepad connected at index " + gp.index + ": " + gp.id +
" with " + gp.buttons.length + " buttons, " + gp.axes.length + " axes."
);
});
console.log("Listening for gamepadconnected — press a button on your pad");Also listen for gamepaddisconnected to clear UI when a pad is unplugged.
Inspect the first connected pad’s primary button and stick axes.
function describeFirstPad() {
if (!navigator.getGamepads) return "getGamepads not supported";
const gp = Array.from(navigator.getGamepads()).find(Boolean);
if (!gp) return "No active gamepad";
const btn0 = gp.buttons[0];
return [
"id: " + gp.id,
"button0.pressed: " + (btn0 ? btn0.pressed : "n/a"),
"button0.value: " + (btn0 ? btn0.value : "n/a"),
"axes: [" + gp.axes.map((a) => a.toFixed(2)).join(", ") + "]"
].join("\n");
}
console.log(describeFirstPad());Analog triggers often use button.value (0–1), not only pressed.
Beginner game-loop pattern: poll pads each animation frame.
let frames = 0;
function pollGamepads() {
frames += 1;
const pads = navigator.getGamepads
? Array.from(navigator.getGamepads()).filter(Boolean)
: [];
if (frames <= 3) {
console.log("frame " + frames + " pads=" + pads.length);
}
if (frames < 3) {
requestAnimationFrame(pollGamepads);
} else {
console.log("Stopped demo poll after 3 frames");
}
}
requestAnimationFrame(pollGamepads);In a real game, keep polling while the scene is active and read axes/buttons each frame.
index.navigator.getGamepads() WorksPress a button; the browser fires gamepadconnected.
Read the array and pick the pad by index (skip null).
Inside requestAnimationFrame, refresh buttons and axes.
Apply movement, actions, and menus from the latest snapshot.
null — always guard when looping.navigator.getGamepads() is Baseline Widely available across modern browsers (MDN: since March 2017). Controllers still usually need a user button press before they appear in the array. Always skip null slots and poll during gameplay.
Array snapshot of Gamepad objects — buttons, axes, and stable indexes.
Bottom line: Listen for gamepadconnected, call getGamepads() for snapshots, filter nulls, and poll buttons/axes each animation frame.
navigator.getGamepads() is the Baseline way to snapshot connected controllers. Wait for a button press / gamepadconnected, skip null slots, then poll buttons and axes in your game loop.
Continue with getInstalledRelatedApps(), getBattery(), or the JavaScript hub.
gamepadconnected / gamepaddisconnectednull entries in the returned arraygetGamepads() each animation frame during playSecurityErrornull holesgetGamepads()Snapshot controllers — connect event, then poll each frame.
Gamepad array
ValueWidely available
Since 2017null slots OK
Indexespress a button
Connectpoll each frame
rAFA Gamepad object from an earlier poll can go stale. Always call navigator.getGamepads() again (or re-read the same index) when you need fresh button and axis values.
Hide install banners when related apps are already installed.
8 people found this page helpful