The HTML5 Gamepad API is one of the more exciting HTML5 APIs in my opinion. It allows a website to pretty easily take input from a game controller that is connected to the user’s machine. The API supports hundreds of game controllers, both wireless and wired, including Xbox One controllers and PS4 controllers to name a few.
Before we begin, note that the gamepad API may not detect a gamepad until you press a button or move a stick on the controller. So, make sure to press some of the buttons when you test any sites or programs that use the Gamepad API.
Note: controllers and other game inputs are referred to as ‘gamepads’ throughout this article and in the gamepad API documentation.
Checking if Your Gamepad is Connected and Troubleshooting Potential Issues
To check if your gamepad is successfully connected, run
If your gamepad isn’t working with the API, here are a few things to try:
- check if the device is connected to your machine via bluetooth, USB, or other method
- try restarting your computer or web browser
- try pressing some of the buttons or moving one of the sticks on the controller so that it is detected
- try closing any other games or apps that are using the gamepad
Get a List of Connected Gamepads
The Gamepad API allows up to four gamepads to be connected at once.
To get an array of connected gamepads, use the
navigator.getGamepads() method. The array is always of length four, where unused gamepad slots are
null. The element(s) of connected gamepad(s) are
Gamepad object(s). Here’s an example value of the
Before trying to use a the functionality of the Gamepad API, make sure a gamepad is connected using the instructions in the previous section.
Gamepad object includes two important properties that are available in the vast majority of all gamepads and controllers:
axes is an array of length four which represents the position of the left and right sticks in the gamepad. The first two elements in
axes are the (x, y) coordinates of the position of the left stick, whereas the third and fourth elements in
axes are the (x, y) coordinates of the position of the right stick. (x, y) values are numbers between -1 and 1 where the (0, 0) means the stick is has not moved.
In the horizontal axes (first and third elements in
-1 would indicate the stick is moved fully to the left, and 1 would mean the stick is moved fully to the right. In the vertical axes (second and fourth elements in
-1 would indicate the stick is moved fully to the top, and 1 would mean the stick is moved fully to the bottom.
Here’s an example value of
axes with explanations in the comments:
Contrary to buttons in HTML, event listeners cannot be added to gamepad buttons. Instead, you can check if a button is currently pressed by using the boolean
pressed property in the element in the
Here’s a list of button indexes are their Xbox and PS4 Equivalents in the HTML5 Gamepad API:
| Index | Button
.pressed Code | Button on Xbox | Button on PlayStation |
| 0 |
gamepad.buttons.pressed | A | X |
| 1 |
gamepad.buttons.pressed | B | O |
| 2 |
gamepad.buttons.pressed | X | Square |
| 3 |
gamepad.buttons.pressed | Y | Triangle |
| 4 |
gamepad.buttons.pressed | LB | L1 |
| 5 |
gamepad.buttons.pressed | RB | R1 |
| 6 |
gamepad.buttons.pressed | LT | L2 |
| 7 |
gamepad.buttons.pressed | RT | R2 |
| 8 |
gamepad.buttons.pressed | Show Address Bar | Share |
| 9 |
gamepad.buttons.pressed | Show Menu | Options |
| 10 |
gamepad.buttons.pressed | Left Stick Pressed | Left Stick Pressed |
| 11 |
gamepad.buttons.pressed | Right Stick Pressed | Right Stick Pressed |
| 12 |
gamepad.buttons.pressed | Directional Up | Directional Up |
| 13 |
gamepad.buttons.pressed | Directional Down | Directional Down |
| 14 |
gamepad.buttons.pressed | Directional Left | Directional Left |
| 15 |
gamepad.buttons.pressed | Directional Right | Directional Right |
| 16 |
gamepad.buttons.pressed | Xbox Light-Up Logo | PlayStation Logo |
Here's an example of checking if Button One (A on Xbox, X on PS4) is pressed:
Detect When a Gamepad Has Been Connected
The name of the event when a gamepad has been connected to the user’s machine is
gamepadconnected. The event argument that is passed into the event function includes a
gamepad property, which is a
Gamepad object for the gamepad the has been connected.
Instead of accessing this gamepad directly, it is more common to get the index of this gamepad in the
navigator.getGamepads() array by using the
Gamepad.index. For example:
A More Complicated Example
Here's an example program that displays which buttons on a controller are pressed at a given time. Try running this code and pressing buttons on your gamepad; you should see that the indexes of the buttons that are pressed is displayed.
The HTML5 Gamepad API has complete support in most modern web browsers today. However, there are a few browsers that don't yet support it as of December 2020, including:
- IE (11)
- Opera Mini
- Opera Mobile
- Android Browser
- KaiOS Browser
For more up-to-date information on browser support, see the Gamepad API's CanIUse Page.
I hope this helps in learning how to use the HTML5 Gamepad API. While the API is not yet widely used in online games at the moment, it can still be useful for a number of projects and can be fun to try out.
Thanks for scrolling.
— Gabriel Romualdo, December 15, 2020