| Attribute | Detail |
|---|---|
| Authors | Matt Reynolds (Google), Marcos Cáceres(Apple), Sun Shin (NVIDIA) |
| Contacts | mattreynolds@google.com, caceres_m@apple.com, sushin@nvidia.com |
| Status | Explainer |
| Chromium Bug | https://issues.chromium.org/issues/339841686 |
| ChromeStatus | https://chromestatus.com/feature/5075054393163776 |
| WebKit Bug | https://bugs.webkit.org/show_bug.cgi?id=266293 |
| Specification Proposal | https://github.com/w3c/gamepad/pull/196 |
This proposal extends the Gamepad API by introducing a new type attribute on GamepadButton.
The attribute enables web applications to identify whether a button is part of the Standard Gamepad mapping, represents a controller-specific extension, or corresponds to a trackpad input.
The primary motivation for this proposal is improving support for controller touchpads through a standardized and interoperable mechanism. At the same time, the proposed enumeration provides useful classification information for existing and future controller inputs.
The proposal is fully backward compatible with existing Gamepad API implementations.
This proposal is being developed as an extension to the W3C Gamepad API specification.
Specification work is currently under discussion within the Web Applications Working Group and is tracked through the following pull request:
The proposal introduces:
GamepadButtonType enumGamepadButton.type attributeSpecification status:
Specification currently under development in a Working Group.
Implementation is under review in Chromium:
WebKit has active implementation work for the same proposal:
The existence of implementation efforts across multiple browser engines helps validate the usefulness and interoperability of the proposed API.
The Gamepad API currently exposes button state through GamepadButton objects, including whether a button is pressed, touched, and its analog value.
However, applications do not have access to information describing the role of a button within a controller mapping.
Applications frequently need to determine whether a button is part of the Standard Gamepad mapping or represents a controller-specific extension. In addition, modern controllers increasingly expose specialized inputs such as touchpads that developers may wish to identify explicitly.
Today, these distinctions generally require controller-specific button index mappings and custom application logic.
The Gamepad API exposes button state through GamepadButton objects, but it does not provide information about the role of a button within a controller’s mapping.
Applications frequently need to determine whether a button is part of the Standard Gamepad mapping or represents a controller-specific extension.
Examples include:
Today, web applications typically rely on controller-specific button indices and custom mapping logic to make these distinctions.
By exposing button type information directly through the Gamepad API, applications can identify standard buttons, non-standard buttons, and touchpad buttons using a consistent and interoperable mechanism.
Several game controllers expose integrated touchpads that are used by games as distinct input mechanisms.
For example, cloud gaming services may wish to display prompts such as:
Press the touchpad.
Without explicit button classification information, applications must rely on controller-specific button indices and mapping tables to identify these controls.
Providing a dedicated trackpad button type allows applications to recognize this functionality directly through the platform.
This proposal aims to:
This proposal does not:
The proposal adds a new readonly type attribute to GamepadButton.
enum GamepadButtonType {
"non-standard",
"standard",
"trackpad",
};
partial interface GamepadButton {
readonly attribute GamepadButtonType type;
};
| Value | Description |
|---|---|
standard |
Represents a button whose type is defined by the Standard Gamepad mapping. |
non-standard |
Represents a button that exists on the controller but does not have a corresponding standard button type. |
trackpad |
Represents a trackpad input type. |
Trackpad inputs are represented as a dedicated button classification because they have known cross-device semantics and existing web developer use cases.
In contrast, non-standard is intended for controller-specific buttons that do not correspond to a standardized button type.
const gamepad = navigator.getGamepads()[0];
for (const button of gamepad.buttons) {
if (button.type === "trackpad") {
console.log("Trackpad button detected");
}
}
if (button.type === "trackpad") {
showPrompt("Press the touchpad");
}
for (const button of gamepad.buttons) {
if (button.type === "non-standard") {
console.log("Controller-specific button");
}
}
const standardButtons = gamepad.buttons.filter(
button => button.type === "standard"
);
The current proposal introduces three button classifications:
standardnon-standardtrackpadThese classifications address current web developer needs while providing a structured mechanism for future evolution.
Any future additions would require separate specification review and Working Group consensus.
This proposal exposes limited information about controller input classifications that are already observable through controller behavior and existing mappings.
The proposal does not expose:
The additional fingerprinting surface is expected to be minimal.
The proposal is read-only.
It does not introduce any new device capabilities and does not modify the existing Gamepad API security model.
No additional permissions are required.
The proposal is fully backward compatible.
Existing content will continue to function without modification.
Applications can detect support using:
if ("type" in GamepadButton.prototype) {
// Feature supported.
}