Controller button mapping, index by index

The complete index table

The Position column is quoted from the button table in the W3C Gamepad specification, and the Chromium column gives the name the browser's own code uses for the same index — declared in the same order, which is how you can see the two documents agree. The four controller columns are this site's contribution; the specification never names a vendor.

The Nintendo problem, stated precisely

Nintendo prints its face-button letters in the opposite arrangement to Microsoft. Because the API numbers positions, the letters move with the position rather than the index. On an Xbox controller the button marked A is buttons[0]; on a Switch Pro Controller the button marked A is buttons[1]. B is buttons[1] on Xbox and buttons[0] on the Pro Controller. The two pads print the same thing at exactly 4 of the 17 canonical indices, and all 4 are the d-pad directions (D-pad ↑, D-pad ↓, D-pad ←, D-pad →).

This is not the browser being sloppy — it is the browser being consistent. Chromium's Nintendo mapping code assigns BUTTON_INDEX_PRIMARY from the controller's button_b field, and the neighbouring array literal comments the four entries "// B button", "// A button", "// Y button", "// X button" in that order. The browser has decided, correctly, that the position is what the index means. The consequence for anyone shipping software is blunt: never print a face-button letter from an index unless you have first read the controller's id and decided which letter set applies. The Switch Pro controller test shows the source that settles it, and the Xbox controller tester is the other half of the comparison if you have both pads to hand.

Where the two PlayStation pads disagree

The DualSense and the DualShock 4 are the easy case. Across all 17 canonical indices they differ at exactly 1: buttons[8], the left button in center cluster, where Sony renamed the DualShock 4's Share button to Create on the DualSense. The position, the index and the behaviour are identical; only the printing changed. Code written against indices needs no changes between the two generations, which is precisely the payoff the canonical layout exists to deliver. The PS4 controller test takes that further and checks the browser's own mapper source for both pads.

Index 17: the buttons that do not fit

The Standard Gamepad ends at 16, and real controllers kept adding buttons afterwards. Chromium handles this by appending the extra input immediately after the canonical set, so on each of these devices the extra button lands at index 17. The enum names below are the identifiers in Chromium's source, and the last column names the mapper files where the assignment is actually written — which is not the same question as where the name is declared.

The last column is where the surprise lives. Three of these four are assigned on all three desktop platforms; the Xbox Share button is assigned only by the macOS and Linux mappers, in a function that runs after the ordinary Xbox Bluetooth mapper and raises the reported button count. Chromium's Windows mapper has no equivalent row, so a Series X|S pad does not report the same button count everywhere. The Linux file does not even reuse the shared name — it declares its own constant at the same value — which is exactly why the column says where the assignment happens instead of leaving you to infer it from an enum.

Notice too that all four rows share an index. Index 17 alone tells you nothing about which button was pressed — it is a touchpad click on one pad and a capture button on another. The only way to disambiguate is the controller's id string, which the device panel in the tool prints in full. This also explains a reading you may already have seen: a pad reporting 18 buttons where you expected 17 is not broken and is not "extra standard"; it is a standard pad plus one appended extra.

When the table does not apply at all

Everything above is conditional on your controller reporting mapping === "standard". The property is an enumeration with three legal values and no others.

If yours reports the empty string, the fastest route to a correct mapping is to build your own in about thirty seconds: open the live panel, press each button in a fixed order, and write down the index that lights. That list is authoritative for your device in a way no published chart can be. It is also worth repeating the exercise if you use the pad through an adapter, because the adapter — not the controller — is what the browser identifies, and two adapters for the same controller can produce two different orderings.

Advice for people writing code against this

• Bind by index, label by id. Read buttons[0], but decide whether to draw "A", "Cross" or "B" from the device string.
• Check mapping before trusting an index. One equality test separates the devices your layout describes from the ones it does not.
• Do not assume 17. Iterate buttons.length; extras start at index 17, are device-specific, and on the Xbox Series X|S are platform-specific as well.
• Remember the vertical axes point down. axes[1] and axes[3] are positive downward, which the specification states outright and which inverts roughly half of all first drafts.
• Read value, not pressed, at indices 6 and 7. The flag is a convenience with a browser-chosen threshold baked into it; apply your own trigger dead zone and let the player set it. And do not assume those two indices are analog at all — the analog trigger test shows what a digital one looks like.
• Offer a remap screen anyway. Every assumption above fails for some real device; a rebinding UI is the only complete answer.

Checking your own pad against the table

The live panel above shows each canonical index with its value, so you can verify the table against your hardware in a minute. Press the bottom face button and confirm index 0 lights. Push the left stick right and confirm axes[0] goes positive; push it down and confirm axes[1] goes positive too — that is the one that surprises people. Then squeeze each trigger slowly and watch buttons[6] and buttons[7] climb continuously, with no snap straight to 1, which is the subject of the analog trigger test. If any of these disagree with the table, check mapping first — it explains the overwhelming majority of mismatches.