use-bluetooth

Connect to Bluetooth Low Energy devices with the Web Bluetooth API.


Package	`@vizejs/composable/use-bluetooth`
Own the source	`vize lib pull composable:use-bluetooth`
Runtime exports	`useBluetooth`
Gzip budget	2560 B

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useBluetooth } from "@vizejs/composable/use-bluetooth";

Try it

Pair a heart-rate monitor

Request a Bluetooth device by service and connect to it, with a clear message where Web Bluetooth is missing.

Open the interactive example

What to observe: In Chromium on desktop, Pair a monitor opens the device chooser. Other browsers show that Web Bluetooth is not available.

requestOptions filters the chooser by GATT service. read and notifications are available once connected. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Pair a heart-rate monitor: initial state — Initial state

Pair a heart-rate monitor: state after the verified interactions — After the verified interactions

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useBluetooth } from "@vizejs/composable/use-bluetooth";
import { useMounted } from "@vizejs/composable/use-mounted";

const mounted = useMounted();
const { supported, device, connected, error, requestDevice, connect, disconnect } = useBluetooth({
  requestOptions: { filters: [{ services: ["heart_rate"] }] },
});

async function pair() {
  if (await requestDevice()) await connect();
}
</script>

<template>
  <div class="composable-example">
    <p>Pair a Bluetooth heart-rate monitor, or explain why the browser cannot.</p>
    <div class="example-actions">
      <button type="button" :disabled="!mounted || !supported || connected" @click="pair">
        Pair a monitor
      </button>
      <button type="button" :disabled="!connected" @click="() => disconnect()">Disconnect</button>
    </div>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : !supported
          ? "Web Bluetooth is not available in this browser."
          : connected
            ? `Connected to ${device?.name ?? "the monitor"}.`
            : error
              ? "Pairing was cancelled or failed."
              : "Ready to pair."
    }}</output>
  </div>
</template>

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useBluetooth`	system	experimental	deterministic-fallback	caller-managed	reactive-scope, returned-value	web, desktop	`window`	`tryOnScopeDispose`

API

`useBluetooth`

Connect to Bluetooth Low Energy devices with the Web Bluetooth API. requestDevice() prompts for a device, connect() connects its GATT server, and read / write / notify address characteristics by service and characteristic UUID. connected follows gattserverdisconnected and available follows availabilitychanged. Failures land in error. Notifications are stopped and the server disconnected when the owning reactive scope stops; outside a scope call disconnect(). Server rendering: supported, available and connected are false and nothing is queried. Inside a component the host is resolved after mounting, so hydration renders this server state first.

function useBluetooth(options: UseBluetoothOptions = {}): BluetoothControls

const ble = useBluetooth({ requestOptions: { filters: [{ services: ["heart_rate"] }] } });
await ble.requestDevice();
await ble.connect();
await ble.notify("heart_rate", "heart_rate_measurement", (value) => show(value.getUint8(1)));

Types

`BluetoothDeviceFilter`

Scan filter for requestDevice.

Member	Type	Description
`services`?	`readonly BluetoothUUIDLike[]`	Services the device must advertise.
`name`?	`string`	Exact device name.
`namePrefix`?	`string`	Device name prefix.

`BluetoothCharacteristicLike`

Minimal BluetoothRemoteGATTCharacteristic used by useBluetooth.

Member	Type	Description
`value`?	`DataView \| null \| undefined`	Last read or notified value.
`readValue`	`() => Promise<DataView>`	Read the value.
`writeValueWithResponse`	`(value: BufferSource) => Promise<void>`	Write and wait for the device's acknowledgement.
`writeValueWithoutResponse`	`(value: BufferSource) => Promise<void>`	Write without acknowledgement.
`startNotifications`	`() => Promise<unknown>`	Start `characteristicvaluechanged` notifications.
`stopNotifications`	`() => Promise<unknown>`	Stop notifications.

`BluetoothServiceLike`

Minimal BluetoothRemoteGATTService.

Member	Type	Description
`getCharacteristic`	`(characteristic: BluetoothUUIDLike) => Promise<BluetoothCharacteristicLike>`	Look up a characteristic.

`BluetoothGATTServerLike`

Minimal BluetoothRemoteGATTServer.

Member	Type	Description
`connected`	`boolean`	Whether the server is connected.
`connect`	`() => Promise<unknown>`	Connect to the server.
`disconnect`	`() => void`	Disconnect from the server.
`getPrimaryService`	`(service: BluetoothUUIDLike) => Promise<BluetoothServiceLike>`	Look up a primary service.

`BluetoothDeviceLike`

Minimal BluetoothDevice used by useBluetooth.

Member	Type	Description
`id`	`string`	Opaque device identifier.
`name`?	`string \| undefined`	Advertised name.
`gatt`?	`BluetoothGATTServerLike \| undefined`	GATT server, when the device supports GATT.

`BluetoothHost`

navigator.bluetooth-like capability used by useBluetooth.

Member	Type	Description
`getAvailability`	`() => Promise<boolean>`	Whether a Bluetooth adapter is available.
`requestDevice`	`(options: BluetoothRequestOptions) => Promise<BluetoothDeviceLike>`	Prompt the user for a device.

`UseBluetoothOptions`

Options for useBluetooth.

Member	Type	Description
`host`?	`MaybeRefOrGetter<BluetoothHost \| null \| undefined>`	`navigator.bluetooth`-like capability.
`requestOptions`?	`BluetoothRequestOptions`	Default options for `requestDevice()`.

`BluetoothControls`

Reactive state and actions returned by useBluetooth.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether Web Bluetooth is available.
`available`	`Readonly<Ref<boolean>>`	Whether an adapter is available, following `availabilitychanged`.
`device`	`Readonly<ShallowRef<BluetoothDeviceLike \| undefined>>`	Most recently chosen device.
`connected`	`Readonly<Ref<boolean>>`	Whether the device's GATT server is connected.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure.
`requestDevice`	`( options?: BluetoothRequestOptions, ) => Promise<BluetoothDeviceLike \| undefined>`	Prompt the user for a device (requires user activation). Disconnects the previous device.
`connect`	`() => Promise<boolean>`	Connect to the device's GATT server.
`disconnect`	`() => void`	Stop notifications and disconnect the GATT server. Idempotent.
`read`	`( service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, ) => Promise<DataView \| undefined>`	Read a characteristic.
`write`	`( service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, value: BufferSource, options?: { readonly withoutResponse?: boolean }, ) => Promise<boolean>`	Write a characteristic, with a response unless `withoutResponse`.
`notify`	`( service: BluetoothUUIDLike, characteristic: BluetoothUUIDLike, listener: (value: DataView) => void, ) => Promise<BluetoothNotificationStop \| undefined>`	Subscribe to characteristic notifications.