useBluetooth

browser

Installation

npx usehooks-cli@latest add use-bluetooth

Description

A comprehensive hook for interacting with Bluetooth Low Energy devices using the Web Bluetooth API. Provides device discovery, connection management, and GATT characteristic operations.

Parameters

Name	Type	Default	Description
options?	UseBluetoothOptions	-	Default options for device requests

Parameter Properties

options properties:

Name	Type	Description
filters?	BluetoothLEScanFilter[]	Filters to apply when scanning for devices
optionalServices?	BluetoothServiceUUID[]	Optional services to access on the device
acceptAllDevices?	boolean	Whether to accept all devices (used when no filters specified)

Return Type

UseBluetoothReturn

Property	Type	Description
device	BluetoothDeviceInfo \| null	Information about the currently selected device
isSupported	boolean	Whether Web Bluetooth API is supported
isAvailable	boolean \| null	Whether Bluetooth is available on the device
isConnecting	boolean	Whether a connection attempt is in progress
error	string \| null	Error message if any operation failed
requestDevice	(options?: BluetoothRequestDeviceOptions) => Promise<BluetoothDeviceInfo \| null>	Request access to a Bluetooth device
connect	() => Promise<boolean>	Connect to the selected device
disconnect	() => Promise<void>	Disconnect from the current device
readCharacteristic	(serviceUuid: BluetoothServiceUUID, characteristicUuid: BluetoothServiceUUID) => Promise<DataView \| null>	Read a value from a GATT characteristic
writeCharacteristic	(serviceUuid: BluetoothServiceUUID, characteristicUuid: BluetoothServiceUUID, value: BufferSource) => Promise<boolean>	Write a value to a GATT characteristic
startNotifications	(serviceUuid: BluetoothServiceUUID, characteristicUuid: BluetoothServiceUUID, callback: (value: DataView) => void) => Promise<boolean>	Start receiving notifications from a characteristic
stopNotifications	(serviceUuid: BluetoothServiceUUID, characteristicUuid: BluetoothServiceUUID) => Promise<boolean>	Stop receiving notifications from a characteristic

Examples

Basic Device Connection

Connect to a Bluetooth device and check connection status

import { useBluetooth } from '@usehooks/use-bluetooth';

function BluetoothConnector() {
  const {
    device,
    isSupported,
    isConnecting,
    error,
    requestDevice,
    connect,
    disconnect
  } = useBluetooth();

  const handleRequestDevice = async () => {
    await requestDevice({
      acceptAllDevices: true
    });
  };

  const handleConnect = async () => {
    const success = await connect();
    if (success) {
      console.log('Connected successfully');
    }
  };

  if (!isSupported) {
    return <div>Web Bluetooth not supported</div>;
  }

  return (
    <div>
      <button onClick={handleRequestDevice} disabled={isConnecting}>
        Select Device
      </button>
      
      {device && (
        <div>
          <p>Device: {device.name || 'Unknown'}</p>
          <p>Status: {device.connected ? 'Connected' : 'Disconnected'}</p>
          
          {!device.connected ? (
            <button onClick={handleConnect} disabled={isConnecting}>
              {isConnecting ? 'Connecting...' : 'Connect'}
            </button>
          ) : (
            <button onClick={disconnect}>Disconnect</button>
          )}
        </div>
      )}
      
      {error && <p>Error: {error}</p>}
    </div>
  );
}

Heart Rate Monitor

Connect to a heart rate monitor and read heart rate data

import { useBluetooth } from '@usehooks/use-bluetooth';
import { useState, useEffect } from 'react';

function HeartRateMonitor() {
  const {
    device,
    requestDevice,
    connect,
    readCharacteristic,
    startNotifications
  } = useBluetooth();
  const [heartRate, setHeartRate] = useState<number | null>(null);

  const connectToHeartRateMonitor = async () => {
    // Request heart rate monitor
    await requestDevice({
      filters: [{ services: ['heart_rate'] }]
    });
  };

  useEffect(() => {
    if (device?.connected) {
      // Start heart rate notifications
      startNotifications(
        'heart_rate',
        'heart_rate_measurement',
        (value) => {
          // Parse heart rate value (first byte after flags)
          const rate = value.getUint8(1);
          setHeartRate(rate);
        }
      );
    }
  }, [device?.connected, startNotifications]);

  return (
    <div>
      <button onClick={connectToHeartRateMonitor}>
        Connect Heart Rate Monitor
      </button>
      
      {device && (
        <div>
          <p>Device: {device.name}</p>
          {!device.connected ? (
            <button onClick={connect}>Connect</button>
          ) : (
            <div>
              <p>Status: Connected</p>
              {heartRate && (
                <p>Heart Rate: {heartRate} BPM</p>
              )}
            </div>
          )}
        </div>
      )}
    </div>
  );
}

Custom Service Communication

Read from and write to custom GATT characteristics

import { useBluetooth } from '@usehooks/use-bluetooth';
import { useState } from 'react';

function CustomDeviceController() {
  const {
    device,
    requestDevice,
    connect,
    readCharacteristic,
    writeCharacteristic
  } = useBluetooth();
  const [data, setData] = useState<string>('');
  const [inputValue, setInputValue] = useState('');

  const SERVICE_UUID = '12345678-1234-1234-1234-123456789abc';
  const READ_CHAR_UUID = '87654321-4321-4321-4321-cba987654321';
  const WRITE_CHAR_UUID = '11111111-2222-3333-4444-555555555555';

  const connectToDevice = async () => {
    await requestDevice({
      filters: [{ services: [SERVICE_UUID] }],
      optionalServices: [SERVICE_UUID]
    });
  };

  const readData = async () => {
    const value = await readCharacteristic(SERVICE_UUID, READ_CHAR_UUID);
    if (value) {
      const decoder = new TextDecoder();
      const text = decoder.decode(value);
      setData(text);
    }
  };

  const writeData = async () => {
    const encoder = new TextEncoder();
    const data = encoder.encode(inputValue);
    const success = await writeCharacteristic(SERVICE_UUID, WRITE_CHAR_UUID, data);
    if (success) {
      console.log('Data written successfully');
      setInputValue('');
    }
  };

  return (
    <div>
      <button onClick={connectToDevice}>Select Device</button>
      
      {device && !device.connected && (
        <button onClick={connect}>Connect</button>
      )}
      
      {device?.connected && (
        <div>
          <button onClick={readData}>Read Data</button>
          <p>Read Value: {data}</p>
          
          <div>
            <input
              value={inputValue}
              onChange={(e) => setInputValue(e.target.value)}
              placeholder="Enter data to write"
            />
            <button onClick={writeData}>Write Data</button>
          </div>
        </div>
      )}
    </div>
  );
}

Dependencies

react

Notes

•Only available in browsers that support Web Bluetooth API (Chrome 56+, Edge 79+)
•Requires HTTPS in production environments
•User gesture required to initiate device requests
•Device permissions are persistent across sessions
•Automatically handles disconnection events and cleanup
•GATT characteristics are cached for performance

Implementation

"use client";

import { useState, useCallback, useRef, useEffect } from "react";

type BluetoothServiceUUID = number | string;

interface BluetoothManufacturerDataFilter {
  companyIdentifier: number;
  dataPrefix?: BufferSource;
  mask?: BufferSource;
}

interface BluetoothLEScanFilter {
  services?: BluetoothServiceUUID[];
  name?: string;
  namePrefix?: string;
  manufacturerData?: BluetoothManufacturerDataFilter[];
}

type BluetoothRequestDeviceOptions =
  | {
      filters: BluetoothLEScanFilter[];
      optionalServices?: BluetoothServiceUUID[];
      acceptAllDevices?: false;
    }
  | {
      acceptAllDevices: boolean;
      optionalServices?: BluetoothServiceUUID[];
      filters?: undefined;
    };

interface BluetoothRemoteGATTCharacteristic {
  value?: DataView | null;
  readValue(): Promise<DataView>;
  writeValue(value: BufferSource): Promise<void>;
  startNotifications(): Promise<BluetoothRemoteGATTCharacteristic>;
  stopNotifications(): Promise<BluetoothRemoteGATTCharacteristic>;
  addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions
  ): void;
}

interface BluetoothRemoteGATTService {
  getCharacteristic(
    characteristicUuid: BluetoothServiceUUID
  ): Promise<BluetoothRemoteGATTCharacteristic>;
}

interface BluetoothRemoteGATTServer {
  connected: boolean;
  disconnect(): void;
  getPrimaryService(
    serviceUuid: BluetoothServiceUUID
  ): Promise<BluetoothRemoteGATTService>;
}

interface BluetoothRemoteGATT {
  connected: boolean;
  connect(): Promise<BluetoothRemoteGATTServer>;
}

interface BluetoothDevice {
  id: string;
  name?: string;
  gatt?: BluetoothRemoteGATT;
  addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions
  ): void;
}

interface BluetoothAPI {
  requestDevice(options: BluetoothRequestDeviceOptions): Promise<BluetoothDevice>;
  getAvailability?(): Promise<boolean>;
}

type NavigatorWithBluetooth = Navigator & {
  bluetooth?: BluetoothAPI;
};

interface BluetoothDeviceInfo {
  id: string;
  name: string | undefined;
  connected: boolean;
}

interface UseBluetoothOptions {
  filters?: BluetoothLEScanFilter[];
  optionalServices?: BluetoothServiceUUID[];
  acceptAllDevices?: boolean;
}

interface UseBluetoothReturn {
  device: BluetoothDeviceInfo | null;
  isSupported: boolean;
  isAvailable: boolean | null;
  isConnecting: boolean;
  error: string | null;
  requestDevice: (
    options?: BluetoothRequestDeviceOptions
  ) => Promise<BluetoothDeviceInfo | null>;
  connect: () => Promise<boolean>;
  disconnect: () => Promise<void>;
  readCharacteristic: (
    serviceUuid: BluetoothServiceUUID,
    characteristicUuid: BluetoothServiceUUID
  ) => Promise<DataView | null>;
  writeCharacteristic: (
    serviceUuid: BluetoothServiceUUID,
    characteristicUuid: BluetoothServiceUUID,
    value: BufferSource
  ) => Promise<boolean>;
  startNotifications: (
    serviceUuid: BluetoothServiceUUID,
    characteristicUuid: BluetoothServiceUUID,
    callback: (value: DataView) => void
  ) => Promise<boolean>;
  stopNotifications: (
    serviceUuid: BluetoothServiceUUID,
    characteristicUuid: BluetoothServiceUUID
  ) => Promise<boolean>;
}

export const useBluetooth = (
  options: UseBluetoothOptions = {}
): UseBluetoothReturn => {
  const [device, setDevice] = useState<BluetoothDeviceInfo | null>(null);
  const [isAvailable, setIsAvailable] = useState<boolean | null>(null);
  const [isConnecting, setIsConnecting] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const deviceRef = useRef<BluetoothDevice | null>(null);
  const serverRef = useRef<BluetoothRemoteGATTServer | null>(null);
  const characteristicsRef =
    useRef<Map<string, BluetoothRemoteGATTCharacteristic>>(new Map());

  // Check if Web Bluetooth API is supported
  const isSupported =
    typeof navigator !== "undefined" &&
    typeof (navigator as NavigatorWithBluetooth).bluetooth !== "undefined";

  // Check Bluetooth availability
  useEffect(() => {
    const bluetooth =
      typeof navigator === "undefined"
        ? undefined
        : (navigator as NavigatorWithBluetooth).bluetooth;

    if (isSupported && bluetooth?.getAvailability) {
      bluetooth
        .getAvailability()
        .then(setIsAvailable)
        .catch(() => setIsAvailable(false));
    } else {
      setIsAvailable(false);
    }
  }, [isSupported]);

  // Request Bluetooth device
  const requestDevice = useCallback(
    async (
      requestOptions?: BluetoothRequestDeviceOptions
    ): Promise<BluetoothDeviceInfo | null> => {
      if (!isSupported) {
        setError("Web Bluetooth API is not supported");
        return null;
      }

      const bluetooth = (navigator as NavigatorWithBluetooth).bluetooth;
      if (!bluetooth) {
        setError("Web Bluetooth API is not supported");
        return null;
      }

      try {
        setError(null);
        const deviceOptions: BluetoothRequestDeviceOptions = requestOptions
          ? requestOptions
          : options.filters && options.filters.length > 0
            ? {
                filters: options.filters,
                optionalServices: options.optionalServices,
              }
            : {
                acceptAllDevices: options.acceptAllDevices ?? true,
                optionalServices: options.optionalServices,
              };

        const bluetoothDevice = await bluetooth.requestDevice(deviceOptions);

        deviceRef.current = bluetoothDevice;
        const deviceInfo: BluetoothDeviceInfo = {
          id: bluetoothDevice.id,
          name: bluetoothDevice.name ?? undefined,
          connected: bluetoothDevice.gatt?.connected || false,
        };

        setDevice(deviceInfo);

        // Listen for disconnection
        bluetoothDevice.addEventListener("gattserverdisconnected", () => {
          setDevice((prev) => (prev ? { ...prev, connected: false } : null));
          serverRef.current = null;
          characteristicsRef.current.clear();
        });

        return deviceInfo;
      } catch (err) {
        const errorMessage =
          err instanceof Error ? err.message : "Failed to request device";
        setError(errorMessage);
        return null;
      }
    },
    [isSupported, options]
  );

  // Connect to device
  const connect = useCallback(async (): Promise<boolean> => {
    if (!deviceRef.current) {
      setError("No device selected");
      return false;
    }

    try {
      setIsConnecting(true);
      setError(null);

      const server = await deviceRef.current.gatt?.connect();
      if (server) {
        serverRef.current = server;
        setDevice((prev) => (prev ? { ...prev, connected: true } : null));
        return true;
      }

      setError("Failed to connect to GATT server");
      return false;
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to connect";
      setError(errorMessage);
      return false;
    } finally {
      setIsConnecting(false);
    }
  }, []);

  // Disconnect from device
  const disconnect = useCallback(async (): Promise<void> => {
    if (serverRef.current && serverRef.current.connected) {
      serverRef.current.disconnect();
    }
    serverRef.current = null;
    characteristicsRef.current.clear();
    setDevice((prev) => (prev ? { ...prev, connected: false } : null));
  }, []);

  // Get characteristic helper
  const getCharacteristic = useCallback(
    async (
      serviceUuid: BluetoothServiceUUID,
      characteristicUuid: BluetoothServiceUUID
    ): Promise<BluetoothRemoteGATTCharacteristic | null> => {
      if (!serverRef.current) {
        setError("Not connected to device");
        return null;
      }

      const key = `${serviceUuid}-${characteristicUuid}`;

      if (characteristicsRef.current.has(key)) {
        return characteristicsRef.current.get(key)!;
      }

      try {
        const service = await serverRef.current.getPrimaryService(serviceUuid);
        const characteristic =
          await service.getCharacteristic(characteristicUuid);
        characteristicsRef.current.set(key, characteristic);
        return characteristic;
      } catch (err) {
        const errorMessage =
          err instanceof Error ? err.message : "Failed to get characteristic";
        setError(errorMessage);
        return null;
      }
    },
    []
  );

  // Read characteristic value
  const readCharacteristic = useCallback(
    async (
      serviceUuid: BluetoothServiceUUID,
      characteristicUuid: BluetoothServiceUUID
    ): Promise<DataView | null> => {
      const characteristic = await getCharacteristic(
        serviceUuid,
        characteristicUuid
      );
      if (!characteristic) return null;

      try {
        setError(null);
        const value = await characteristic.readValue();
        return value;
      } catch (err) {
        const errorMessage =
          err instanceof Error ? err.message : "Failed to read characteristic";
        setError(errorMessage);
        return null;
      }
    },
    [getCharacteristic]
  );

  // Write characteristic value
  const writeCharacteristic = useCallback(
    async (
      serviceUuid: BluetoothServiceUUID,
      characteristicUuid: BluetoothServiceUUID,
      value: BufferSource
    ): Promise<boolean> => {
      const characteristic = await getCharacteristic(
        serviceUuid,
        characteristicUuid
      );
      if (!characteristic) return false;

      try {
        setError(null);
        await characteristic.writeValue(value);
        return true;
      } catch (err) {
        const errorMessage =
          err instanceof Error ? err.message : "Failed to write characteristic";
        setError(errorMessage);
        return false;
      }
    },
    [getCharacteristic]
  );

  // Start notifications
  const startNotifications = useCallback(
    async (
      serviceUuid: BluetoothServiceUUID,
      characteristicUuid: BluetoothServiceUUID,
      callback: (value: DataView) => void
    ): Promise<boolean> => {
      const characteristic = await getCharacteristic(
        serviceUuid,
        characteristicUuid
      );
      if (!characteristic) return false;

      try {
        setError(null);
        await characteristic.startNotifications();

        const handleNotification = (event: Event) => {
          const target = event.target as BluetoothRemoteGATTCharacteristic | null;
          if (target?.value) {
            callback(target.value);
          }
        };

        characteristic.addEventListener(
          "characteristicvaluechanged",
          handleNotification
        );
        return true;
      } catch (err) {
        const errorMessage =
          err instanceof Error ? err.message : "Failed to start notifications";
        setError(errorMessage);
        return false;
      }
    },
    [getCharacteristic]
  );

  // Stop notifications
  const stopNotifications = useCallback(
    async (
      serviceUuid: BluetoothServiceUUID,
      characteristicUuid: BluetoothServiceUUID
    ): Promise<boolean> => {
      const characteristic = await getCharacteristic(
        serviceUuid,
        characteristicUuid
      );
      if (!characteristic) return false;

      try {
        setError(null);
        await characteristic.stopNotifications();
        return true;
      } catch (err) {
        const errorMessage =
          err instanceof Error ? err.message : "Failed to stop notifications";
        setError(errorMessage);
        return false;
      }
    },
    [getCharacteristic]
  );

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (serverRef.current && serverRef.current.connected) {
        serverRef.current.disconnect();
      }
    };
  }, []);

  return {
    device,
    isSupported,
    isAvailable,
    isConnecting,
    error,
    requestDevice,
    connect,
    disconnect,
    readCharacteristic,
    writeCharacteristic,
    startNotifications,
    stopNotifications,
  };
};

useVibration

CLI Docs All Hooks

useClipboard