JavaScript Navigator usb Property

What You’ll Learn

navigator.usb is the entry point for the WebUSB API. Learn the USB object, requestDevice / getDevices, connect events, secure context rules, five examples, and try-it labs.

Introduction

USB devices range from custom gadgets and Arduino-style boards to specialty hardware that does not fit neatly into serial or HID protocols. WebUSB lets a web page talk to those devices — with the user’s permission.

navigator.usb is read-only. When WebUSB is available, it returns a USB object you use to request access, list previously paired devices, and listen for connect / disconnect events.

Understanding the usb Property

Think of navigator.usb as the WebUSB “front desk.” The real work happens on the USB object it returns.

• USB object — entry point with methods and events.
• requestDevice() — user picks a device and grants access (returns a USBDevice).
• getDevices() — list previously paired attached devices.
• connect / disconnect — events when paired devices appear or leave.
• Filters — limit the picker by vendorId, productId, and related fields.
• Experimental — feature-detect; do not require it for core UX.

📝 Syntax

General form of the property:

navigator.usb

Value

• A USB object when WebUSB is available in this context.
• Missing / unavailable when unsupported, insecure, or blocked.

Common patterns

// Feature-detect:
if ("usb" in navigator && navigator.usb) {
  // WebUSB entry point is available
}

// Request a device (must run from a click handler):
async function pickDevice() {
  const filters = [
    { vendorId: 0x1209, productId: 0xa800 },
    { vendorId: 0x1209, productId: 0xa850 }
  ];
  const device = await navigator.usb.requestDevice({ filters });
  console.log(device.productName);
}

// List previously paired devices:
const known = await navigator.usb.getDevices();

Examples Gallery

Examples follow MDN WebUSB / navigator.usb patterns. Prefer Try It Yourself on HTTPS in a Chromium browser with a real USB device. requestDevice needs a button click.

const supported = Boolean(navigator.usb);
console.log(supported ? "WebUSB available" : "WebUSB missing");

WebUSB missing
(or "WebUSB available" in a supporting browser)

console.log("secure: " + window.isSecureContext);
console.log("usb: " + Boolean(navigator.usb));

if (!window.isSecureContext) {
  console.log("Serve over HTTPS to use WebUSB");
} else if (!navigator.usb) {
  console.log("Secure, but WebUSB not exposed");
} else {
  console.log("Ready to call getDevices / requestDevice");
}

secure: true
usb: false
Secure, but WebUSB not exposed
(messages vary by browser and URL)

async function listPaired() {
  if (!navigator.usb) {
    return "WebUSB not supported.";
  }
  const devices = await navigator.usb.getDevices();
  return "paired devices: " + devices.length;
}

listPaired().then(console.log);

WebUSB not supported.
(or "paired devices: 0" / a positive count)

async function pickUsbDevice() {
  if (!navigator.usb) {
    throw Error("WebUSB not supported.");
  }
  // Demo filters from MDN-style vendor/product IDs — replace with your hardware.
  const filters = [
    { vendorId: 0x1209, productId: 0xa800 },
    { vendorId: 0x1209, productId: 0xa850 }
  ];
  const device = await navigator.usb.requestDevice({ filters });
  return "Selected: " + (device.productName || "USB device");
}

// Call pickUsbDevice() from a button onclick — not on page load.

WebUSB not supported.
(or product name / cancel error message)

function watchUsb() {
  if (!navigator.usb) {
    return { ok: false, message: "WebUSB not supported." };
  }
  navigator.usb.addEventListener("connect", (e) => {
    console.log("USB connected:", e.device.productName);
  });
  navigator.usb.addEventListener("disconnect", (e) => {
    console.log("USB disconnected:", e.device.productName);
  });
  return { ok: true, message: "Listening for connect / disconnect" };
}

console.log(JSON.stringify(watchUsb()));

{"ok":false,"message":"WebUSB not supported."}
(or listening message when supported)

🚀 Common Use Cases

• Custom USB gadgets — configure devices that speak a vendor USB protocol.
• Firmware / flashing tools — browser-based updaters for supported boards.
• Lab / education demos — teach USB transfers without a native installer.
• Specialty hardware dashboards — meters, cameras, or instruments with WebUSB support.
• Progressive enhancement — WebUSB when available; otherwise guide users to another path.

📝 Notes

• Experimental — not Baseline; feature-detect always.
• Secure context required (HTTPS / localhost).
• Returns a USB object; main methods are requestDevice() and getDevices().
• requestDevice() needs transient user activation (a click).
• Related: userActivation, serial, hid, bluetooth.

💡 Best Practices