1---
2category: Browser
3---
4 
5# useBluetooth
6 
7Reactive [Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API). Provides the ability to connect and interact with Bluetooth Low Energy peripherals.
8 
9The Web Bluetooth API lets websites discover and communicate with devices over the Bluetooth 4 wireless standard using the Generic Attribute Profile (GATT).
10 
11N.B. It is currently partially implemented in Android M, Chrome OS, Mac, and Windows 10. For a full overview of browser compatibility please see [Web Bluetooth API Browser Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API#browser_compatibility)
12 
13N.B. There are a number of caveats to be aware of with the web bluetooth API specification. Please refer to the [Web Bluetooth W3C Draft Report](https://webbluetoothcg.github.io/web-bluetooth/) for numerous caveats around device detection and connection.
14 
15N.B. This API is not available in Web Workers (not exposed via WorkerNavigator).
16 
17## Usage Default
18 
19```vue
20<script setup lang="ts">
21import { useBluetooth } from '@vueuse/core'
22 
23const {
24  isSupported,
25  isConnected,
26  device,
27  requestDevice,
28  server,
29  error,
30} = useBluetooth({
31  acceptAllDevices: true,
32})
33</script>
34 
35<template>
36  <button @click="requestDevice()">
37    Request Bluetooth Device
38  </button>
39  <div v-if="error">
40    Error: {{ error }}
41  </div>
42</template>
43```
44 
45### Return Values
46 
47| Property        | Type                             | Description                                |
48| --------------- | -------------------------------- | ------------------------------------------ |
49| `isSupported`   | `ComputedRef<boolean>`           | Whether the Web Bluetooth API is supported |
50| `isConnected`   | `Ref<boolean>`                   | Whether a device is currently connected    |
51| `device`        | `Ref<BluetoothDevice>`           | The connected Bluetooth device             |
52| `server`        | `Ref<BluetoothRemoteGATTServer>` | The GATT server for the connected device   |
53| `error`         | `Ref<unknown>`                   | Any error that occurred during connection  |
54| `requestDevice` | `() => Promise<void>`            | Function to request a Bluetooth device     |
55 
56When the device has paired and is connected, you can then work with the server object as you wish.
57 
58## Usage Battery Level Example
59 
60This sample illustrates the use of the Web Bluetooth API to read battery level and be notified of changes from a nearby Bluetooth Device advertising Battery information with Bluetooth Low Energy.
61 
62Here, we use the characteristicvaluechanged event listener to handle reading battery level characteristic value. This event listener will optionally handle upcoming notifications as well.
63 
64```vue
65<script setup lang="ts">
66import { useBluetooth, useEventListener, watchPausable } from '@vueuse/core'
67 
68const {
69  isSupported,
70  isConnected,
71  device,
72  requestDevice,
73  server,
74} = useBluetooth({
75  acceptAllDevices: true,
76  optionalServices: [
77    'battery_service',
78  ],
79})
80 
81const batteryPercent = ref<undefined | number>()
82 
83const isGettingBatteryLevels = ref(false)
84 
85async function getBatteryLevels() {
86  isGettingBatteryLevels.value = true
87 
88  // Get the battery service:
89  const batteryService = await server.getPrimaryService('battery_service')
90 
91  // Get the current battery level
92  const batteryLevelCharacteristic = await batteryService.getCharacteristic(
93    'battery_level',
94  )
95 
96  // Listen to when characteristic value changes on `characteristicvaluechanged` event:
97  useEventListener(batteryLevelCharacteristic, 'characteristicvaluechanged', (event) => {
98    batteryPercent.value = event.target.value.getUint8(0)
99  }, { passive: true })
100 
101  // Convert received buffer to number:
102  const batteryLevel = await batteryLevelCharacteristic.readValue()
103 
104  batteryPercent.value = await batteryLevel.getUint8(0)
105}
106 
107const { stop } = watchPausable(isConnected, (newIsConnected) => {
108  if (!newIsConnected || !server.value || isGettingBatteryLevels.value)
109    return
110  // Attempt to get the battery levels of the device:
111  getBatteryLevels()
112  // We only want to run this on the initial connection, as we will use an event listener to handle updates:
113  stop()
114})
115</script>
116 
117<template>
118  <button @click="requestDevice()">
119    Request Bluetooth Device
120  </button>
121</template>
122```
123 
124More samples can be found on [Google Chrome's Web Bluetooth Samples](https://googlechrome.github.io/samples/web-bluetooth/).
125 
126## Type Declarations
127 
128```ts
129export interface UseBluetoothRequestDeviceOptions {
130  /**
131   *
132   * An array of BluetoothScanFilters. This filter consists of an array
133   * of BluetoothServiceUUIDs, a name parameter, and a namePrefix parameter.
134   *
135   */
136  filters?: BluetoothLEScanFilter[] | undefined
137  /**
138   *
139   * An array of BluetoothServiceUUIDs.
140   *
141   * @see https://developer.mozilla.org/en-US/docs/Web/API/BluetoothRemoteGATTService/uuid
142   *
143   */
144  optionalServices?: BluetoothServiceUUID[] | undefined
145}
146export interface UseBluetoothOptions
147  extends UseBluetoothRequestDeviceOptions, ConfigurableNavigator {
148  /**
149   *
150   * A boolean value indicating that the requesting script can accept all Bluetooth
151   * devices. The default is false.
152   *
153   * !! This may result in a bunch of unrelated devices being shown
154   * in the chooser and energy being wasted as there are no filters.
155   *
156   *
157   * Use it with caution.
158   *
159   * @default false
160   *
161   */
162  acceptAllDevices?: boolean
163}
164export declare function useBluetooth(
165  options?: UseBluetoothOptions,
166): UseBluetoothReturn
167export interface UseBluetoothReturn extends Supportable {
168  isConnected: Readonly<ShallowRef<boolean>>
169  device: ShallowRef<BluetoothDevice | undefined>
170  requestDevice: () => Promise<void>
171  server: ShallowRef<BluetoothRemoteGATTServer | undefined>
172  error: ShallowRef<unknown | null>
173}
174```
175