Registry / communication / react-native-ble-plx

react-native-ble-plx

library3.5.1jsnpmunverified

react-native-ble-plx is a comprehensive React Native library providing a low-level API for interacting with Bluetooth Low Energy (BLE) devices on both iOS and Android platforms. The current stable version is 3.5.1, with recent releases indicating an active development and maintenance cadence addressing bugs and improvements. It supports core BLE functionalities such as observing the Bluetooth adapter state, scanning for devices, connecting to peripherals, discovering services and characteristics, reading/writing characteristic values, observing notifications/indications, reading RSSI, and negotiating MTU. A key differentiator is its inclusion of an Expo config plugin for easier integration into managed Expo workflows (requiring prebuilding). The library explicitly does not support Bluetooth Classic, inter-phone BLE communication (peripheral mode), device bonding, or beacon technologies. It is built to provide robust control over BLE interactions in React Native applications.

communication

npm install react-native-ble-plx

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-BLE-P

react-native-ble-plx

communicationjavascriptv3.5.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BleManager

✓ import { BleManager } from 'react-native-ble-plx';

✗ const BleManager = require('react-native-ble-plx').BleManager;

The primary class for managing BLE operations. CommonJS `require` is generally discouraged in modern React Native projects due to ESM prevalence.

State

✓ import { State } from 'react-native-ble-plx';

✗ import { BluetoothState } from 'react-native-ble-plx';

Used to access and monitor the current Bluetooth adapter state (e.g., poweredOn, poweredOff). The enum is named `State`, not `BluetoothState`.

Device

✓ import type { Device } from 'react-native-ble-plx';

✗ import { Device } from 'react-native-ble-plx';

Primarily used as a TypeScript type for device objects returned by scan and connection methods. While it can be imported as a value, it's typically used for type annotations.

Characteristic

✓ import type { Characteristic } from 'react-native-ble-plx';

✗ import { Characteristic } from 'react-native-ble-plx';

Primarily used as a TypeScript type for characteristic objects. Similar to `Device`, it's generally imported as a type.

Initializes the BleManager, requests necessary Bluetooth permissions for Android, monitors Bluetooth adapter state, and performs a device scan, logging found devices. It also demonstrates how to handle state changes and stop scanning.

import { BleManager, State } from 'react-native-ble-plx'; import { PermissionsAndroid, Platform } from 'react-native'; const manager = new BleManager(); async function requestBluetoothPermissions() { if (Platform.OS === 'ios') { return true; // iOS handles permissions differently, usually in Info.plist } if (Platform.OS === 'android') { const apiLevel = Platform.Version; if (apiLevel < 31) { // Android 11 (API 30) and below const granted = await PermissionsAndroid.request( PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION, { title: 'Location Permission', message: 'Bluetooth Low Energy requires Location Permission', buttonNeutral: 'Ask Me Later', buttonNegative: 'Cancel', buttonPositive: 'OK', } ); return granted === PermissionsAndroid.RESULTS.GRANTED; } else { // Android 12 (API 31) and above const granted = await PermissionsAndroid.requestMultiple([ PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN, PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT, PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION, ]); return ( granted['android.permission.BLUETOOTH_SCAN'] === PermissionsAndroid.RESULTS.GRANTED && granted['android.permission.BLUETOOTH_CONNECT'] === PermissionsAndroid.RESULTS.GRANTED && granted['android.permission.ACCESS_FINE_LOCATION'] === PermissionsAndroid.RESULTS.GRANTED ); } } return false; } export const scanForDevices = async () => { const hasPermission = await requestBluetoothPermissions(); if (!hasPermission) { console.log('Bluetooth permissions not granted.'); return; } const subscription = manager.onStateChange((state) => { if (state === State.PoweredOn) { console.log('Bluetooth is powered on, starting scan...'); manager.startDeviceScan(null, { allowDuplicates: false }, (error, device) => { if (error) { console.error('Scan error:', error); return; } if (device) { console.log('Found device:', device.name || device.id); // Example: Stop scan after finding one device manager.stopDeviceScan(); // subscription.remove(); // Unsubscribe from state changes } }); subscription.remove(); // Remove state change listener after successful scan initiation } else { console.log('Bluetooth state:', state); } }, true); }; // To stop scanning, typically called after a timeout or finding a device // manager.stopDeviceScan(); // Don't forget to destroy the manager when your component unmounts or app closes // manager.destroy();

Debug

Known issues

breakingIn version 3.2.0, several methods (`destroyClient`, `cancelTransaction`, `setLogLevel`, `startDeviceScan`, `stopDeviceScan`) were changed to return Promises. Previously, these might have been synchronous or returned void. Existing code that does not await these calls or handle their new Promise return type will break.

fix

Ensure all calls to `destroyClient`, `cancelTransaction`, `setLogLevel`, `startDeviceScan`, and `stopDeviceScan` are `await`ed or have `.then().catch()` handlers.

affects: >=3.2.0

breakingMajor version 3.0.0 involved significant internal updates, including `MultiplatformBleAdapter` to 0.2.0, RN bridge config, and dependency updates, alongside fixes for iOS 16 bugs. While not explicitly detailed as breaking, such changes often introduce subtle incompatibilities.

fix

Thoroughly test your application when upgrading from v2.x to v3.0.0+. Pay attention to Bluetooth operations, especially on iOS 16, and review any direct interaction with native modules if custom bridges are in use.

affects: >=3.0.0

gotchaAs of version 3.4.0, `BleManager` is implemented as a singleton. While this aims to simplify its usage in React components/hooks, it changes the underlying behavior. If you were instantiating `BleManager` multiple times and expecting distinct instances, this will no longer be the case.

fix

Ensure your application design accounts for a single `BleManager` instance. If you were creating multiple instances for different purposes, you might need to refactor to use a single manager and manage its state and operations carefully.

affects: >=3.4.0

gotchaUsing `react-native-ble-plx` with Expo requires the application to be prebuilt (`npx expo prebuild`). It is not compatible with 'Expo Go' because it relies on custom native code. Failing to prebuild will result in runtime errors.

fix

For Expo projects, add `react-native-ble-plx` to the `plugins` array in `app.json` or `app.config.js` and run `npx expo prebuild` before building or running your app on a device or simulator.

affects: >=3.1.0

gotchaProper Bluetooth permissions are crucial for the library to function. On Android, this involves `ACCESS_FINE_LOCATION` (for Android 11 and below), and `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`, `ACCESS_FINE_LOCATION` (for Android 12/API 31 and above). iOS requires entries in `Info.plist` for `NSBluetoothAlwaysUsageDescription` and `NSBluetoothPeripheralUsageDescription`.

fix

Implement robust runtime permission requests for Android and ensure `Info.plist` is correctly configured for iOS. Lack of permissions will lead to scanning or connection failures without clear error messages from the library.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of null (reading 'getDeviceID') OR Service.getDeviceID()' on a null object reference

Attempts to access properties on a null object, often due to race conditions or incorrect cleanup during service/characteristic discovery. Fixed in v3.5.1 for specific cases.

fix

Upgrade to `react-native-ble-plx@3.5.1` or newer. Implement robust error handling and null checks around device, service, and characteristic access after discovery. Ensure `BleManager.destroy()` is called when no longer needed.

Promise.reject crash with null arguments

A specific bug on Android where internal promise rejections were sometimes made with null arguments, leading to a crash. Fixed in v3.5.1.

fix

Upgrade to `react-native-ble-plx@3.5.1` or newer to resolve this Android-specific crash.

Error: You cannot use this package in Expo Go. It requires custom native code.

Attempting to run a project using `react-native-ble-plx` in the 'Expo Go' app.

fix

For Expo projects, ensure you are using a custom development client or a prebuilt standalone app. Add the config plugin to `app.json` and run `npx expo prebuild`.

Bluetooth scan fails or no devices found, despite Bluetooth being on.

Missing or improperly granted Bluetooth permissions on Android or incorrect `Info.plist` entries on iOS.

fix

Verify that all necessary Android permissions (`ACCESS_FINE_LOCATION`, `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT` as per API level) are requested and granted at runtime. For iOS, confirm `NSBluetoothAlwaysUsageDescription` and `NSBluetoothPeripheralUsageDescription` are present and correctly filled in `Info.plist`.

TypeError: Cannot read properties of undefined (reading 'callMethod') or 'this' context issues on Android.

Older versions (prior to 3.2.1) had issues with `this` context for some methods after React Native Fast Refresh on Android.

fix

Upgrade to `react-native-ble-plx@3.2.1` or newer to benefit from fixes related to `this` context and Fast Refresh on Android.

Upgrade

Version history

3.5.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency, core React framework.

react-nativerequiredPeer dependency, core React Native framework.

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/dotintent/react-native-ble-plx ↗

packagehttps://www.npmjs.com/package/react-native-ble-plx ↗