API in Capabilities
WebHID API
Published
navigator.hid.requestDevice() lets users grant a PWA access to connected Human Interface Devices through a browser chooser. The chooser lists devices matching your filters and returns the selected HIDDevice objects. An opened device sends input reports as inputreport events and accepts output and feature reports as byte buffers. With HID over USB or Bluetooth, a PWA can control a macro pad or game controller, as well as a barcode scanner or lab instrument.
Support is desktop Chromium only: Chrome 89 and Edge 89 on Windows, macOS, Linux, and ChromeOS implement HID, HIDDevice, requestDevice(), and getDevices(); Chrome 100 added HIDDevice.forget(), and Chrome 131 exposes navigator.hid in dedicated workers (BCD api.HID, api.HID.worker_support). Chrome for Android, Android WebView, Firefox, and Safari report no support, and WebKit has filed a formal “oppose” position (standards-positions #510).
Syntax
Section titled “Syntax”navigator.hid.requestDevice(options)navigator.hid.getDevices()
device.open()device.close()device.forget()device.sendReport(reportId, data)device.sendFeatureReport(reportId, data)device.receiveFeatureReport(reportId)requestDevice() and getDevices() return a Promise<sequence<HIDDevice>>; requestDevice() resolves with an empty sequence, not a rejection, when the user dismisses the chooser. open(), close(), forget(), sendReport(), and sendFeatureReport() return Promise<undefined>; receiveFeatureReport() returns a Promise<DataView> whose first byte may be the report ID. navigator.hid is [SecureContext] and requestDevice() additionally needs a Window global with transient user activation. Each HIDDevice exposes opened, vendorId, productId, productName, and collections, and fires inputreport (HIDInputReportEvent with device, reportId, data); navigator.hid fires connect and disconnect (HIDConnectionEvent with device) for previously granted devices.
Parameters
Section titled “Parameters”requestDevice() takes one HIDDeviceRequestOptions dictionary.
| Member | Type | Required | Description |
|---|---|---|---|
filters |
sequence<HIDDeviceFilter> |
Yes | Devices matching any filter are listed; [] lists every connected HID device the browser does not block. |
exclusionFilters |
sequence<HIDDeviceFilter> |
No | Devices matching any of these are hidden even when they match filters. Must be non-empty when present. |
Every HIDDeviceFilter member is optional, but a filter is only valid when productId comes with vendorId and usage comes with usagePage.
| Member | Type | Description |
|---|---|---|
vendorId |
unsigned long |
USB-IF vendor ID, for example 0x046d for Logitech. |
productId |
unsigned short |
Product ID; requires vendorId. |
usagePage |
unsigned short |
HID usage page of a top-level collection, for example 0x0001 Generic Desktop or 0xff00 and above for vendor-defined pages. |
usage |
unsigned short |
Usage ID within usagePage; requires usagePage. |
sendReport(), sendFeatureReport(), and receiveFeatureReport() take a reportId (octet, 0 when the interface does not use report IDs) and, for the two send methods, a BufferSource data holding the report payload without the ID byte.
Exceptions
Section titled “Exceptions”requestDevice() and getDevices() reject before any chooser appears when one of the following holds.
| Exception | Condition |
|---|---|
SecurityError |
The document is not allowed to use the hid Permissions Policy feature, or (requestDevice() only) the call has no transient user activation. |
NotSupportedError |
requestDevice() was called from a global that is not a Window, such as a worker. |
TypeError |
A filter in filters or exclusionFilters is not valid (productId without vendorId, usage without usagePage), or exclusionFilters is present but empty. |
The HIDDevice methods reject as follows.
| Method | Exception | Condition |
|---|---|---|
open() |
InvalidStateError |
The device state is not "closed" (already open, opening, or forgotten). |
open() |
NetworkError |
The operating system refused to open the device. |
close() |
none | Resolves; any pending sendReport() or feature-report promise is rejected with AbortError. |
forget() |
InvalidStateError |
Chromium: another open() or forget() call on the device is still in progress. |
sendReport(), sendFeatureReport(), receiveFeatureReport() |
InvalidStateError |
The device is not "opened". |
| the same three | TypeError |
reportId is 0 on an interface that uses report IDs, or non-zero on one that does not. |
| the same three | NotAllowedError |
The report is on the browser’s blocked list (for example reports on protected keyboard or FIDO collections). |
| the same three | NetworkError |
The operating system failed to write or read the report. |
A blocked input report raises no exception at all: the browser drops it without firing inputreport.
Examples
Section titled “Examples”Check for navigator.hid before using WebHID. Firefox, Safari, and Android lack this property and need a fallback.
Pairing a vendor-specific device and opening it
Section titled “Pairing a vendor-specific device and opening it”Filter on the vendor ID so the chooser lists only that manufacturer’s devices, take the first granted device, and open it. The call must sit inside the click handler. Without WebHID the handler shows a message pointing to the manufacturer’s desktop utility instead.
const LOGITECH = 0x046d;
document.querySelector('#pair').addEventListener('click', async () => { const note = document.querySelector('#hid-note'); if (!('hid' in navigator)) { note.textContent = 'This browser cannot talk to HID devices; use the vendor utility to configure it.'; return; }
const [device] = await navigator.hid.requestDevice({ filters: [{ vendorId: LOGITECH }] }); if (!device) return; // chooser dismissed: an empty array, not an error
if (!device.opened) await device.open(); note.textContent = `Connected to ${device.productName} (${device.vendorId.toString(16)}:${device.productId.toString(16)})`;});requestDevice() resolves with an empty array when the user closes the chooser, so destructuring and testing device covers the cancel case without a try/catch.
Reading input reports from a custom controller
Section titled “Reading input reports from a custom controller”After open(), each report the device sends arrives as an inputreport event with a DataView of the payload. The handler decodes a two-byte vendor report into a dial value and a button bitmap; the layout comes from the device’s report descriptor, which device.collections exposes if you need to inspect it at runtime.
function listenToDial(device, onChange) { if (!('hid' in navigator)) return () => {};
const handler = (event) => { if (event.reportId !== 0x01) return; const position = event.data.getUint8(0); const buttons = event.data.getUint8(1); onChange({ position, pressed: (buttons & 0x01) !== 0 }); }; device.addEventListener('inputreport', handler); return () => device.removeEventListener('inputreport', handler);}event.data excludes the report ID byte; it is delivered separately as event.reportId, which is 0 on devices whose interface does not number its reports.
Reconnecting granted devices on page load
Section titled “Reconnecting granted devices on page load”Permission survives reloads, so getDevices() returns previously granted devices without a prompt and without needing a gesture. Combine it with the connect and disconnect events to reopen a device that is unplugged and plugged back in while the page is open.
async function restoreDevices(onDevice, onGone) { if (!('hid' in navigator)) return;
for (const device of await navigator.hid.getDevices()) { await device.open(); onDevice(device); } navigator.hid.addEventListener('connect', async ({ device }) => { await device.open(); onDevice(device); }); navigator.hid.addEventListener('disconnect', ({ device }) => onGone(device));}forget() revokes the grant from script, so a “Remove device” button can clear it without sending the user to the site-settings page.
See also
Section titled “See also”- WebUSB API, for USB interfaces that are not HID class
- Web Serial API
- Web Bluetooth API, for Bluetooth Low Energy devices that use GATT instead of HID
- WebHID: requestDevice() method (hid.spec.whatwg.org)
- WebHID: HIDDevice open() method (hid.spec.whatwg.org)
- WebKit standards position: WebHID (github.com)
- Connecting to uncommon HID devices (developer.chrome.com)
Specifications
| Specification | Status |
|---|---|
| WebHID API | WICG draft |
| WebHID: requestDevice() method | WHATWG living standard |
| WebHID: HIDDevice open() method | WHATWG living standard |
| WebHID: HIDDeviceRequestOptions dictionary | WHATWG living standard |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 89 | high | source | — |
| Chrome (Android)# | No | — | high | source | 1 |
| Edge (Desktop)# | Yes | 89 | high | source | 2 |
| Firefox (Desktop)# | No | — | high | source | 3 |
| Firefox (Android)# | No | — | high | source | 45 |
| Safari (macOS)# | No | — | high | source | 6 |
| Safari (iOS)# | No | — | high | source | 78 |
| Samsung Internet# | No | — | high | source | 910 |
| WebView (Android)# | No | — | high | source | 1112 |
- No Chrome Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Firefox for Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Firefox.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- No Samsung Internet support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome Android.
- No WebView Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome Android.