JavaScript Navigator serial Property

What You’ll Learn

navigator.serial is the entry point for the Web Serial API. Learn the Serial object, getPorts / requestPort, connect events, secure context rules, five examples, and try-it labs.

Introduction

Serial ports let computers talk to gadgets line-by-line — microcontrollers (ESP32, micro:bit), 3D printers, USB-CDC adapters, and some Bluetooth devices that expose a virtual serial port.

navigator.serial is read-only. When Web Serial is available, it returns a Serial object. MDN notes the same instance is always returned. You use that object to list granted ports, ask the user to pick a new one, and listen for connect / disconnect events.

Understanding the serial Property

Think of navigator.serial as the Web Serial “front desk.” The real work happens on the Serial object it returns.

• Serial object — entry point with methods and events.
• requestPort() — user picks a port and grants access (returns a SerialPort).
• getPorts() — list ports already granted earlier.
• connect / disconnect — events when devices appear or leave.
• Permissions Policy — if blocked, navigator.serial may be missing entirely.

📝 Syntax

General form of the property:

navigator.serial

Value

• A Serial object when Web Serial is available in this context.
• Missing / unavailable when unsupported, insecure, or blocked by policy.

Common patterns

// Feature-detect:
if ("serial" in navigator && navigator.serial) {
  // Web Serial entry point is available
}

// List ports already granted (MDN page-load pattern):
navigator.serial.getPorts().then((ports) => {
  // Initialize UI with ports
});

// Request a port (must run from a click handler):
async function pickPort() {
  const port = await navigator.serial.requestPort({
    // Optional filters, e.g. { filters: [{ usbVendorId: 0xabcd }] }
  });
  console.log(port);
}

Examples Gallery

Examples follow MDN Web Serial / navigator.serial patterns. Prefer Try It Yourself on HTTPS in a Chromium browser with a real serial device. requestPort needs a button click.

const supported = Boolean(navigator.serial);
console.log(supported ? "Web Serial available" : "Web Serial missing");

Web Serial missing
(or "Web Serial available" in a supporting browser)

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

if (!window.isSecureContext) {
  console.log("Serve over HTTPS to use Web Serial");
} else if (!navigator.serial) {
  console.log("Secure, but Web Serial not exposed");
} else {
  console.log("Ready to call getPorts / requestPort");
}

secure: true
serial: false
Secure, but Web Serial not exposed
(messages vary by browser and URL)

async function listGranted() {
  if (!navigator.serial) {
    return "Web Serial not supported.";
  }
  const ports = await navigator.serial.getPorts();
  return "granted ports: " + ports.length;
}

listGranted().then(console.log);

Web Serial not supported.
(or "granted ports: 0" / a positive count)

async function pickSerialPort() {
  if (!navigator.serial) {
    throw Error("Web Serial not supported.");
  }
  // Demo: no filters = show available ports.
  // Real apps often pass filters: [{ usbVendorId: 0xabcd }]
  const port = await navigator.serial.requestPort();
  return "Port selected (SerialPort object ready)";
}

// Call pickSerialPort() from a button onclick — not on page load.
// Catch errors when the user cancels the dialog.

Web Serial not supported.
(or "Port selected…" / cancel error message)

function watchSerial() {
  if (!navigator.serial) {
    return { ok: false, message: "Web Serial not supported." };
  }
  navigator.serial.addEventListener("connect", (e) => {
    // Connect to e.target or add it to a list of available ports.
    console.log("Serial connected");
  });
  navigator.serial.addEventListener("disconnect", (e) => {
    // Remove e.target from the list of available ports.
    console.log("Serial disconnected");
  });
  return { ok: true, message: "Listening for connect / disconnect" };
}

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

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

🚀 Common Use Cases

• Microcontroller tooling — flash, monitor, or configure ESP32 / micro:bit style boards in the browser.
• 3D printers & CNC — send G-code over a serial connection with user consent.
• Sensor dashboards — stream readings from USB-serial adapters.
• Education / demos — teach serial protocols without installing a native IDE.
• Progressive enhancement — Web Serial when available; otherwise guide users to another path.

📝 Notes

• Limited availability (MDN) — not Baseline; feature-detect always.
• Not Deprecated, Experimental, or Non-standard on current MDN — no status banner required.
• Secure context required (HTTPS / localhost).
• Returns a Serial object; the same instance is always returned.
• Related: hid, serviceWorker, bluetooth, Window.

💡 Best Practices