Home › Controller Support for Browser Games: Gamepad API and Steam Deck (2026)

Controller Support for Browser Games: Gamepad API and Steam Deck (2026)

Players on itch.io, Poki and especially Steam expect to pick up a controller and play. Browsers give you that through the Gamepad API, but it behaves differently from keyboard events: nothing shows up until the player presses a button, there are no button events, and only pads with the “standard” mapping have predictable button numbers. Wrap the game for Steam and a second layer arrives: Steam Input, which presents most controllers to your game as an Xbox pad, plus Valve's Steam Deck rules for glyphs and text entry. This guide covers both, with code you can paste or hand to your coding agent. Every fact comes from MDN, the W3C spec, Valve's Steamworks docs or the engines' own docs.

Last updated:

Free download · one page + PDF · updated weekly, current edition November 16, 2026

🎁 Free: The AI Game Dev Stack 2026

The best AI tool for each job in a solo or indie game (3D, sprites and pixel art, animation, audio, NPCs), MCP setups for Unity, Unreal, Godot and Roblox, and which free plans you can actually ship with.

Yours free when you join the VibeStack Weekly: new AI game-dev tools and releases every Monday, 5-minute read. Unsubscribe anytime.

Quick answers

QuestionShort answer
Do I need a library?No. The Gamepad API is built into browsers; MDN lists it as Baseline, available across browsers since March 2017. Phaser and Godot wrap it for you
Why does getGamepads() return nothing?Browsers hide pads until the player presses a button while your page is visible (an anti-fingerprinting rule). Show “Press any button”
How do I read buttons?Poll navigator.getGamepads() every frame in your requestAnimationFrame loop and compare with last frame. The API only has connect and disconnect events
Which button is which?Only pads reporting mapping === 'standard' use the W3C layout (button 0 = bottom face button, 9 = right center button, 12-15 = d-pad)
What does Steam Deck see?With Steam Input, Valve says the controller “will show up in your game as an Xbox controller”. Standard-mapping code is the right base
What does Deck Verified need?Full controller access with the default config, controller glyphs that match the input in use, an on-screen keyboard for text entry, 30fps at 800p and readable text

This page is about input. For wrapping the game in Electron or Tauri and the Steamworks bindings, see how to put a web game on Steam; for zips, portals and SDKs see how to publish an HTML5 game; Godot users should also read Godot web export for itch.io and Poki. For phones and tablets, see touch controls for HTML5 games (virtual joystick, Pointer Events, mobile portal rules).

The four Gamepad API rules behind most bugs

  1. Nothing until the player presses something. The W3C spec says getGamepads() returns an empty list until a gamepad user gesture has been seen, to stop sites fingerprinting visitors by their hardware. MDN adds that if a pad is already plugged in, gamepadconnected fires when the player presses a button or moves an axis, and that Firefox only exposes gamepads after the player interacts with one while the page is visible. Put “Press any button to play” on your title screen; it doubles as the click-to-start screen browsers need for audio.
  2. Poll every frame and don't keep the object. MDN's guide polls navigator.getGamepads() in each animation frame and reads the current object by index rather than holding on to an old one. There's no “button down” event in the API (just gamepadconnected and gamepaddisconnected), so you detect presses yourself by comparing with the previous frame.
  3. The array has holes. When a pad disconnects its slot can become null so the others keep their index, and MDN notes an index may be reused after a pad reconnects. Always null-check, and pause the game on gamepaddisconnected.
  4. Only “standard” pads have known button numbers. gamepad.mapping is 'standard' when the browser has remapped the device to the W3C layout (MDN's other known value, 'xr-standard', is for XR controllers). Unrecognized devices are exposed raw, with browser-specific numbering. Godot's web export docs warn that mappings can be wrong depending on browser, OS and controller, and that the API gives no reliable way to identify the model and fix it, for privacy reasons. Treat gamepad.id as a display string: MDN says its format isn't strictly specified.

The standard mapping

Positions from the W3C spec's Standard Gamepad layout. The face-button and shoulder names in the last column come from Phaser's docs.

IndexWhere it is (W3C)Usually labeled
buttons[0]Bottom button, right clusterA (Xbox) / X (DualShock)
buttons[1]Right button, right clusterB / Circle
buttons[2]Left button, right clusterX / Square
buttons[3]Top button, right clusterY / Triangle
buttons[4], [5]Top left and top right front buttonsLB/RB (Xbox) / L1/R1 (DualShock)
buttons[6], [7]Bottom left and bottom right front buttonsTriggers, L2/R2 in Phaser; analog, value 0 to 1
buttons[8], [9]Left and right buttons, center clusterUse [9] for pause
buttons[10], [11]Left and right stick pressedStick clicks
buttons[12]-[15]Up, down, left, right in the left clusterD-pad
buttons[16]Center button, center clusterDon't rely on it
axes[0], [1]Left stick X and YNegative is left and up, positive is right and down
axes[2], [3]Right stick X and YSame directions

Each button has pressed (true or false) and value (0 to 1, so triggers are analog); axes run from -1 to 1. The spec lets browsers trim what they expose, for example to exactly the standard number of buttons and axes, so don't depend on extra inputs. “Don't rely on it” for button 16 is our advice.

Polling code you can paste

Plain JavaScript with no dependencies, for a canvas or WebGL game (plain JS or Three.js). It picks the first live pad, applies a radial deadzone, adds the d-pad on standard pads, turns held buttons into one-frame “tapped” events and tracks the last device used so you can switch button prompts. applyInput and onPadLost are yours to write.

// Gamepad input for a canvas/WebGL game (plain JS, Three.js, or alongside Phaser).
const DEADZONE = 0.2;           // starting value; let players change it
const BTN = { A: 0, B: 1, X: 2, Y: 3, LB: 4, RB: 5, LT: 6, RT: 7,
              L_CENTER: 8, R_CENTER: 9, LS: 10, RS: 11, UP: 12, DOWN: 13, LEFT: 14, RIGHT: 15 };
let active = null;              // index of the pad we listen to
let lastDevice = 'keyboard';    // drives which button prompts you draw
const prev = new Map();         // pad index -> buttons pressed last frame

addEventListener('gamepadconnected', (e) => {
  if (active === null) active = e.gamepad.index;
});
addEventListener('gamepaddisconnected', (e) => {
  prev.delete(e.gamepad.index);
  if (e.gamepad.index === active) { active = null; onPadLost(); }
});
addEventListener('keydown', () => { lastDevice = 'keyboard'; });

function deadzone(x, y, dz = DEADZONE) {   // radial: treats the stick as a circle
  const len = Math.hypot(x, y);
  if (len < dz) return { x: 0, y: 0 };
  const k = Math.min(1, (len - dz) / (1 - dz)) / len;
  return { x: x * k, y: y * k };
}

function readPad() {
  const pads = navigator.getGamepads ? navigator.getGamepads() : [];
  let gp = active !== null ? pads[active] : null;   // fresh object every frame
  if (!gp) gp = Array.from(pads).find((p) => p && p.connected) || null;
  if (!gp) return null;
  active = gp.index;
  const now = gp.buttons.map((b) => b.pressed);
  const was = prev.get(gp.index) || [];
  prev.set(gp.index, now);
  if (now.some(Boolean)) lastDevice = 'gamepad';
  const held = (i) => !!now[i];
  const tapped = (i) => !!now[i] && !was[i];          // edge detection
  const move = deadzone(gp.axes[0] || 0, gp.axes[1] || 0);
  if (move.x || move.y) lastDevice = 'gamepad';
  if (gp.mapping === 'standard') {                   // indexes below are only reliable here
    if (held(BTN.LEFT)) move.x = -1;
    if (held(BTN.RIGHT)) move.x = 1;
    if (held(BTN.UP)) move.y = -1;                   // up is negative, like axis 1
    if (held(BTN.DOWN)) move.y = 1;
  }
  return {
    standard: gp.mapping === 'standard',
    move,
    aim: deadzone(gp.axes[2] || 0, gp.axes[3] || 0),
    jump: tapped(BTN.A),
    back: tapped(BTN.B),
    pause: tapped(BTN.R_CENTER),
    fire: (gp.buttons[BTN.RT] ? gp.buttons[BTN.RT].value : 0) > 0.5,  // analog trigger, 0..1
  };
}

function frame() {
  const pad = readPad();
  if (pad) applyInput(pad);     // your game: move, jump, open the pause menu...
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

Download gamepad.js (the same code as a file, MIT license). Pair it with touch-controls.js from our touch controls guide: both return the same −1 to 1 stick range, and the two files load side by side on one page without name clashes. All files: free downloads.

Prompt for your agent (Claude Code, Cursor or OpenAI Codex): “Add Gamepad API support to this game. Poll navigator.getGamepads() in the requestAnimationFrame loop, use the W3C standard mapping only when gamepad.mapping is 'standard', use a radial deadzone with a settings slider, detect presses by comparing with the previous frame, pause on gamepaddisconnected and on visibilitychange, keep keyboard and mouse working, and swap on-screen button prompts to whichever device was used last. Add a debug overlay that lists live button and axis values.”

Browser support caveats

FeatureSupport (MDN compat data)What to do
navigator.getGamepads()Chrome 35, Edge 12, Firefox 29, Safari 10.1Safe to use. Feature-check navigator.getGamepads anyway
gamepadconnected eventWorks via addEventListener in the versions above; the ongamepadconnected property arrived later (Chrome and Edge 143, Firefox 89, Safari 16), and MDN marks the event Baseline 2025Use addEventListener('gamepadconnected', …), and still poll in case it fired before your code ran
Pads visible before a pressNever: the spec and every browser wait for a gamepad gesture; Firefox also needs the page visibleShow a “press any button” prompt
Rumble: vibrationActuator.playEffect()Limited availability: Chrome 68+ and Safari 16.4+ on desktop; not Firefox or Safari on iOS. 'trigger-rumble' is Chrome 126+ onlyFeature-detect, use 'dual-rumble', add an off switch (Godot's docs recommend one too)
Embedded in an iframePermissions Policy gamepad, default allowlist *. If a page blocks it, getGamepads() throws a SecurityError and the events never fireWhen you embed your own game, add allow='gamepad' to the iframe

Rumble details. playEffect() takes duration, startDelay, strongMagnitude and weakMagnitude (plus leftTrigger/rightTrigger for trigger rumble) and returns a promise that resolves to 'complete' or 'preempted'. It rejects when the document is hidden, and the spec stops any playing effect when the page is hidden. Phaser calls its own vibration support “highly experimental”.

HTTPS. The W3C draft and MDN's compat data don't list a secure-context requirement for getGamepads(), but Godot's docs list gamepads among the features that need a secure context, and Phaser's docs warn that Chrome would start requiring HTTPS. itch.io, Poki and Cloudflare Pages all serve HTTPS, so this mostly bites on plain-HTTP self-hosting. localhost is usually treated as secure while testing.

Engine notes

How Steam Input sees a wrapped web game

Valve's Gamepad Emulation guide: on Windows the Steam overlay hooks XInput, DirectInput, RawInput and Windows.Gaming.Input and injects an emulated Xbox controller; on macOS and Linux (SteamOS included) a driver provides the emulated input. Either way the controller “will show up in your game as an Xbox controller”, and inputs an Xbox pad doesn't have get doubled up (for example, PlayStation trackpad click and Options both become Start). Valve says roughly a quarter of controller sessions on Steam in 2020 used Steam Input, including nearly half of PlayStation sessions, and Remote Play uses it while streaming.

For a wrapped game this means:

Text entry on Steam Deck

If a player has to type (a name, a save slot), Deck Verified requires either a Steamworks text-entry API that opens the on-screen keyboard for controller players, or your own controller-only text entry in their language. ISteamUtils has two calls, and steamworks.js wraps both:

Call one when a text field gets focus and the last input was a gamepad, and give players a default name so they can skip typing. That approach is ours. On detecting the Deck: ISteamUtils marks IsSteamRunningOnSteamDeck deprecated as of Steamworks SDK 1.65 in favor of IsRunningOnSteamHardware (Deck, Steam Machine and Steam Frame), and steamworks.js still exposes the older isSteamRunningOnSteamDeck(). Valve also recommends against locking settings by hardware, so decide prompts and keyboards by the input in use, not the device.

Steam Deck Verified checklist for a web port

Valve's compatibility review criteria that touch input and UI, and what each means for a browser game in a wrapper:

Valve's criterionWhat it saysFor a web game
Controller supportAll content reachable with the default controller configuration; players mustn't need to change in-game settings to turn controller support onGamepad support on from the first frame, including menus, settings, pause and quit. No “enable controller” toggle
Controller glyphsGlyphs must match the input in use, “whether it's Deck, Steam Controller, or Xbox glyphs”; no keyboard or mouse glyphs unless that's the active input. Valve strongly recommends the Steam Input API for automatic glyphsSwap prompts on last-used input; never show “Press E” or “Click” to a pad user
Text inputSteamworks on-screen keyboard API, or your own controller-only entryshowFloatingGamepadTextInput on focus, or an on-screen letter grid
PerformanceA default configuration with a playable framerate: 30fps at 800p on Deck (30fps at 1080p on Steam Machine)Test WebGL performance on the device; cap effects by default
Display and text1280x800 (16:10) preferred, 1280x720 accepted; smallest text at least 9 px tall at 1280x800 (Valve recommends 12 px), readable at 12 inches / 30 cmLayouts that scale to 16:10; check your smallest UI text
No compatibility warnings; launchersNo messages that the OS or GPU is unsupported; any launcher must meet the same rulesRemove “best in Chrome” or WebGL-warning screens; skip launchers

Valve's examples of things that drop a game to Playable include needing to pick a community controller configuration, bringing up the on-screen keyboard manually, and using the touchscreen to get through a launcher. Valve says any game Verified on Steam Deck is guaranteed Verified on Steam Machine. The review tests a Linux build first and falls back to Proton for Windows builds, and you can request it for an unreleased game once the standard build review is done.

Testing, with or without a Deck

  1. In browsers. Run the game from a local server, press a button, then check navigator.getGamepads() in the console for mapping and id. Repeat in Chrome, Firefox and Safari with each pad you own: Godot's docs say web controller support varies wildly across browsers.
  2. Hot-plug. Unplug mid-game (the game should pause), plug back in, connect two pads, and switch to keyboard and back to check the prompts swap.
  3. In the wrapper, from Steam. Launch the Electron or Tauri build from your Steam library so Steam Input applies, with Steam Input on and off for the game.
  4. No Deck yet? The Steam Deck FAQ says you can build Deck Steam Input configurations without a dev kit, and Valve recommends a PS4 or PS5 controller for it because they have a gyro and a trackpad.
  5. On a Deck. Install the SteamOS Devkit Client from Steam on your PC, turn on Developer Mode on the Deck (Settings > System), pair it, then use Title Upload with your build folder and start command; tick Steam Play for a Windows build to run it under Proton. The build shows up in the library as “Devkit Game: YourGameName”. Valve says to put steam_appid.txt at the root of the upload (and next to the executable if that's elsewhere), and to install and run another Proton game first.

Pre-ship checklist

Related: put a web game on Steam (Electron, Tauri, steamworks.js) · Steam launch checklist · publish an HTML5 game · Godot web export · touch controls for HTML5 games · AI tools for playtesting and QA · how to vibe code a game

Making a browser game feel right on a controller? Get the VibeStack Weekly digest: new AI game-dev tools and Steam and web publishing changes, every Monday.

Sources (checked October 29, 2026): MDN Web Docs (Gamepad API; Using the Gamepad API; Navigator.getGamepads(); gamepadconnected event; Gamepad.mapping; Gamepad.vibrationActuator; GamepadHapticActuator.playEffect(); Permissions-Policy: gamepad; Window.requestAnimationFrame()) and MDN's browser-compat-data for version numbers; the W3C Gamepad Working Draft (10 July 2025) and editor's draft; Steamworks Documentation (Steam Deck and Steam Machine Compatibility Review; Steam Deck and Steam Machine Recommendations; Steam Deck FAQ; How to load and run games on Steam Deck and Steam Machine; Steam Input Gamepad Emulation: Best Practices; Getting Started with Steam Input for developers; ISteamUtils); the ceifa/steamworks.js type definitions (client.d.ts); Phaser 4.1.0 docs (Gamepad plugin, Gamepad, Axis); Godot 4.7 docs (Controllers, gamepads, and joysticks; Exporting for the Web); Electron docs (WebPreferences). The code, the recommendations and the checklist order are ours, not Valve's or the browser makers'. We haven't tested a wrapped web game on Steam Deck hardware ourselves, so check the results on a device.

Get the Starter Stack ($12) Get the free weekly digest

Our picks (4)

Claude Code

AI Code Editors & Agents

Anthropic's agentic coding tool for the terminal, VS Code and JetBrains. Uses a Claude Pro/Max plan or the API.

#cli#agent
freemium

Cursor

AI Code Editors & Agents

AI-first code editor with agent mode, built on VS Code.

#editor#agent
freemium

OpenAI Codex

AI Code Editors & Agents

OpenAI's coding agent: CLI, IDE extension, web and cloud tasks. Included in ChatGPT plans (Free with limits). Unity ships an official Codex skills plugin (unity@unity-agent-plugin) for Unity 6+. The ModRetro Chromatic plugin (November 2026) builds Game Boy and Game Boy Color games as GB Studio projects, playtests them in a built-in emulator and can flash them to a Chromatic handheld cartridge.

#cli#agent
freemium

GitHub Copilot

AI Code Editors & Agents

AI pair programmer and coding agent across VS Code, JetBrains and the CLI. Free plan available; Gemini 4 Argon on Pro+ and higher.

#editor#agent#github

+ Your tool here

Reach builders, vibe coders & indie game devs. Featured listings from $49/mo.

Advertise →
🧰 The Vibe Coder's Starter Stack: AI rules files, a prompt library and a ship-it checklist. $12.
Get the pack

FAQ

Why does navigator.getGamepads() return an empty array or nulls?

Browsers don't expose a gamepad until the player presses a button or moves a stick while your page is visible; the W3C spec does this to prevent fingerprinting, and Firefox also requires the page to be visible. After a disconnect, a slot can be null so other pads keep their index. Show a “press any button” prompt and null-check every entry.

What is the standard gamepad mapping?

The W3C Gamepad spec's fixed layout: buttons 0-3 are the bottom, right, left and top face buttons, 4-5 the bumpers, 6-7 the analog triggers, 8-9 the center buttons, 10-11 the stick clicks, 12-15 the d-pad and 16 the center button; axes 0-1 are the left stick and 2-3 the right stick, with negative values for left and up. Only pads whose mapping is 'standard' follow it.

How do I add a deadzone to the Gamepad API?

Treat the stick as a circle: compute the length of the (x, y) vector, return zero below the deadzone, and rescale above it so movement starts smoothly. Godot's docs recommend this circular approach and use 0.2 as an example; make the value a setting, as Valve's Steam Input guide also suggests.

Does the Gamepad API work in an Electron game on Steam Deck?

Electron runs Chromium, which supports the Gamepad API. With Steam Input, Valve says controllers show up in games as an Xbox controller (on Linux, through a driver), so standard-mapping code is the right base. We haven't tested it on a Deck ourselves; log gamepad.mapping and gamepad.id on the device to confirm.

Do I need the Steam Input API to get Steam Deck Verified?

Valve's criteria don't require it. They require that the default controller configuration reaches all content and that on-screen glyphs match the input in use (Deck, Steam Controller or Xbox glyphs). Valve strongly recommends the Steam Input API because it picks the correct glyphs automatically.

How do I show the on-screen keyboard in a web game on Steam Deck?

In a Steam build, call ISteamUtils' ShowFloatingGamepadTextInput when a text field gets focus; steamworks.js exposes it as utils.showFloatingGamepadTextInput(mode, x, y, width, height). It types straight into the focused field. ShowGamepadTextInput opens the Big Picture text dialog instead. Valve also accepts your own controller-only text entry.

Does controller vibration work in browsers?

Partly. Gamepad.vibrationActuator.playEffect() with 'dual-rumble' works in Chrome from version 68 and desktop Safari from 16.4, but not in Firefox or Safari on iOS, and 'trigger-rumble' is Chrome 126+ only. Feature-detect it, and give players an off switch.

Does the Gamepad API need HTTPS?

The W3C draft and MDN's compat data don't list a secure-context requirement, but Godot's docs say gamepads need a secure context and Phaser's docs warn that Chrome would require HTTPS. itch.io, Poki and Cloudflare Pages all use HTTPS; localhost usually counts as secure while testing.

Free download · one page + PDF · updated weekly, current edition November 16, 2026

📬 Get the VibeStack Weekly + the free AI Game Dev Stack 2026

The best AI tool for each job in a solo or indie game (3D, sprites and pixel art, animation, audio, NPCs), MCP setups for Unity, Unreal, Godot and Roblox, and which free plans you can actually ship with.

Yours free when you join the VibeStack Weekly: new AI game-dev tools and releases every Monday, 5-minute read. Unsubscribe anytime.