Web Bluetooth: Browser Support, API, Limitations

What is Web Bluetooth?

Web Bluetooth is a JavaScript API that gives a web page access to Bluetooth Low Energy peripherals through the Generic Attribute Profile (GATT), exposed on the navigator.bluetooth object. The Web Bluetooth Community Group at the W3C edits the spec, with Reilly Grant and Ovidio Ruiz-Henriquez at Google as the listed editors. The API first shipped in Chrome 56 in January 2017 and is gated to secure HTTPS contexts and a user-gesture permission prompt for every new device.

Which browsers does Web Bluetooth support?

Chromium-based desktop and Android browsers ship Web Bluetooth, while Firefox and every Safari version on macOS, iOS, and iPadOS leave it out, so global browser support sits near 76% as of April 2026.

What are the key features of the Web Bluetooth API?

The Web Bluetooth API is built around a permission-gated chooser, a GATT client for service discovery, and event-based connection updates. Every call runs in a secure HTTPS context on a top-level page or in an iframe that the parent has unlocked through the bluetooth Permissions-Policy.

• navigator.bluetooth.requestDevice: Pops a browser-supplied device chooser on a click. The user picks a peripheral from a filter list of services, names, or manufacturer data, and the page only sees the device the user picked.
• navigator.bluetooth.getDevices: Returns the list of devices the user has already approved for the origin. The page never gets a free pass to scan nearby radios.
• BluetoothRemoteGATTServer: Connects to and disconnects from the GATT server on the chosen device. Every connection starts with device.gatt.connect and survives until the page calls disconnect or the user revokes permission.
• getPrimaryService and getCharacteristic: Walk the GATT tree to fetch a service and the characteristics inside it. Both methods accept a 16-bit, 32-bit, or 128-bit UUID, or one of the Bluetooth SIG short names like heart_rate or battery_service.
• readValue, writeValue, startNotifications: Read a characteristic value once, write a value, or subscribe to characteristicvaluechanged events. Notifications are how heart rate monitors and CGMs stream live data to the page.
• gattserverdisconnected event: Fires on the BluetoothDevice when the radio link drops. Pages can react to a closed lid, dead battery, or out-of-range device without polling.
• Permissions-Policy bluetooth=self: Cross-origin iframes are blocked by default. The embedder must list bluetooth in its Permissions-Policy header to unlock embedded use.
• Built-in blocklist: Chrome blocks devices that match security-sensitive vendor and product IDs, including some FIDO and HID classes, before the chooser opens. Pages cannot bypass this list.

What are the use cases of Web Bluetooth?

Web Bluetooth lets a web app talk directly to a paired BLE device without a native app or driver. That is the right fit for short-lived configuration tools, wellness dashboards, and IoT control panels. Production sites already use it for health, fitness, education, and hardware control.

• Health and fitness dashboards: Pages that read heart rate from a chest strap, step count from a fitness band, or glucose from a continuous glucose monitor, then sync the data to a cloud account.
• IoT and home automation: Lights, thermostats, locks, and garage door openers that ship with a BLE characteristic the page can flip on a click.
• Firmware updaters and configuration tools: Web pages that flash firmware to drones, e-bikes, or audio gear over the BLE OTA service, replacing a per-platform native installer.
• Maker and education tools: Web Bluetooth controls Arduino, ESP32, BBC micro:bit, and Pixel Kit boards from a tab. Schools and workshops lean on this because no install or app store account is needed.
• Industrial and lab tools: Bluetooth scales, calipers, and multimeters that report measurements straight into a web-based lab notebook.

Paste this snippet into the DevTools console of Chrome, Edge, or Opera over HTTPS. Click anywhere on the page once and the chooser opens, ready to read battery level from any BLE device the user picks.

// Paste this into the DevTools console of Chrome, Edge, or Opera over HTTPS.
// Click anywhere on the page once and the device chooser opens.
if (navigator.bluetooth) {
  console.log("Web Bluetooth is available.");

  document.body.addEventListener("click", async () => {
    try {
      const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
        optionalServices: ["battery_service"],
      });
      console.log("Picked device:", device.name);

      const server = await device.gatt.connect();
      const service = await server.getPrimaryService("battery_service");
      const level = await service.getCharacteristic("battery_level");
      const value = await level.readValue();
      console.log("Battery level:", value.getUint8(0), "percent");
    } catch (err) {
      console.error("Bluetooth request failed:", err.message);
    }
  }, { once: true });
} else {
  console.log("Web Bluetooth is not supported in this browser.");
}

If the console prints "Web Bluetooth is not supported in this browser", you are on Firefox, Safari, or a mobile iOS browser. Fall back to a native helper app or to Bluefy on iOS for those visitors.

What are the limitations of Web Bluetooth?

Web Bluetooth has the smallest footprint of any modern device API outside Chromium. The painful edges show up around Firefox refusal, the Safari and iOS gap, and the rules Chrome layered on top of GATT to keep users safe.

• Firefox calls the API harmful: Mozilla flagged Web Bluetooth in its standards positions list. Sites that need BLE on Firefox must ship a native helper or guide users to Chrome, Edge, or Opera.
• No Safari, no iOS, no iPadOS: WebKit has no Web Bluetooth code. iPad and iPhone users need a third-party app like Bluefy or WebBLE that bundles a separate Bluetooth stack. Chrome on iOS is just WebKit, so it inherits the gap.
• HTTPS only, top-level only: The API throws SecurityError on HTTP and on file:// pages. Cross-origin iframes are blocked unless the parent sends a Permissions-Policy bluetooth=self header.
• requestDevice needs a user gesture: Chrome throws "Must be handling a user gesture" if requestDevice runs from a setTimeout, fetch handler, or page-load script. Wire it to a click or keypress.
• Linux and Windows have version floors: Chrome on Linux ships Web Bluetooth only when chrome://flags/#enable-experimental-web-platform-features is on, and the host needs Linux Kernel 3.19+ with BlueZ 5.41+. Windows needs version 1703 (Creators Update) or later.
• Pairing is not done by the page: The browser shows the chooser, but the OS handles pairing for some classes of devices. Users still pair headsets and watches inside Windows, macOS, or ChromeOS settings before the page sees them.
• No background scanning by default: requestLEScan and watchAdvertisements stay behind chrome://flags/#enable-experimental-web-platform-features. Production sites cannot rely on background advertisement reading yet.
• Built-in blocklist: Chrome blocks vendor and product IDs the team flags as risky, including some FIDO classes. The page cannot bypass this list, even with a custom service UUID.

In my experience, the trickiest failure is the user-gesture rule paired with React. A useEffect that calls requestDevice on mount throws every time, even after a real click somewhere else, because Chrome has already burned the activation token by the time the effect runs. Wire requestDevice to an onClick handler on a real button and the problem disappears.

Citations

All Web Bluetooth version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - Web Bluetooth API: developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API
• MDN Web Docs - Bluetooth interface: developer.mozilla.org/en-US/docs/Web/API/Bluetooth
• W3C Web Bluetooth Community Group - Editor's Draft: webbluetoothcg.github.io/web-bluetooth
• W3C Web Bluetooth Community Group homepage: w3.org/community/web-bluetooth
• Web Bluetooth implementation status: github.com/WebBluetoothCG/web-bluetooth/blob/main/implementation-status.md
• Chrome for Developers - Communicating with Bluetooth devices: developer.chrome.com/docs/capabilities/bluetooth
• Chrome Platform Status - Web Bluetooth feature: chromestatus.com/feature/5264933985976320
• Mozilla Specification Positions: mozilla.github.io/standards-positions
• WebKit Standards Positions: webkit.org/standards-positions
• WebBluetoothCG GitHub repository: github.com/WebBluetoothCG/web-bluetooth