About this library

It supports:

• observing device's Bluetooth adapter state
• scanning BLE devices
• making connections to peripherals
• discovering services/characteristics
• reading/writing characteristics
• observing characteristic notifications/indications
• reading RSSI
• negotiating MTU
• background mode on iOS
• turning the device's Bluetooth adapter on

It does NOT support:

• bluetooth classic devices.
• communicating between phones using BLE (Peripheral support)
• bonding peripherals
• beacons

Table of Contents

1. Compatibility
2. Recent Changes
3. Documentation & Support
4. Configuration & Installation
5. Troubleshooting
6. Releasing
7. Contributions

Compatibility

For old RN versions (<0.60) please check old README (1.x) for the old instructions or migration guide.

React Native	3.1.2
0.81.4	✅
0.74.1	✅
0.69.6	✅
Expo 51	✅

Recent Changes

3.2.0

• Added Android Instance checking before calling its method, an error will be visible on the RN side
• Added information related to Android 14 to the documentation.
• Changed destroyClient, cancelTransaction, setLogLevel, startDeviceScan, stopDeviceScan calls to promises to allow error reporting if it occurs.
• Fixed one of the functions calls that clean up the BLE instance after it is destroyed.

Current version changes All previous changes

Documentation & Support

Interested in React Native project involving Bluetooth Low Energy? We can help you!

Documentation can be found here.

Quick introduction can be found here

Contact us at intent.

Configuration & Installation

Expo SDK 43+

Tested against Expo SDK 49 This package cannot be used in the "Expo Go" app because it requires custom native code. First install the package with yarn, npm, or npx expo install.

After installing this npm package, add the config plugin to the plugins array of your app.json or app.config.js:

{
  "expo": {
    "plugins": ["react-native-ble-plx"]
  }
}

Then you should build the version using native modules (e.g. with npx expo prebuild command). And install it directly into your device with npx expo run:android.

You can find more details in the "Adding custom native code" guide.

API

The plugin provides props for extra customization. Every time you change the props or plugins, you'll need to rebuild (and prebuild) the native app. If no extra properties are added, defaults will be used.

• isBackgroundEnabled (boolean): Enable background BLE support on Android. Adds <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/> to the AndroidManifest.xml. Default false.
• neverForLocation (boolean): Set to true only if you can strongly assert that your app never derives physical location from Bluetooth scan results. The location permission will be still required on older Android devices. Note, that some BLE beacons are filtered from the scan results. Android SDK 31+. Default false. WARNING: This parameter is experimental and BLE might not work. Make sure to test before releasing to production.
• modes (string[]): Adds iOS UIBackgroundModes to the Info.plist. Options are: peripheral, and central. Defaults to undefined.
• bluetoothAlwaysPermission (string | false): Sets the iOS NSBluetoothAlwaysUsageDescription permission message to the Info.plist. Setting false will skip adding the permission. Defaults to Allow $(PRODUCT_NAME) to connect to bluetooth devices.
• iosEnableRestoration (boolean): Opt-in to the iOS BLE state restoration subspec (disabled by default). When true, the Podfile will include react-native-ble-plx/Restoration and the adapter will register with a restoration registry if present.
• iosRestorationIdentifier (string): Custom CBCentralManager restoration identifier. Written to Info.plist as BlePlxRestoreIdentifier and passed to BleManager for state restoration. Defaults to com.reactnativebleplx.restore.

Expo SDK 48 supports iOS 13+ which means NSBluetoothPeripheralUsageDescription is fully deprecated. It is no longer setup in @config-plugins/[email protected] and greater.

Example

{
  "expo": {
  "plugins": [
    [
      "react-native-ble-plx",
      {
        "isBackgroundEnabled": true,
        "modes": ["peripheral", "central"],
        "bluetoothAlwaysPermission": "Allow $(PRODUCT_NAME) to connect to bluetooth devices",
        "iosEnableRestoration": true,
        "iosRestorationIdentifier": "com.example.myapp.bleplx"
      }
    ]
  ]
}
}

Legacy Expo (SDK < 43)

1. Make sure your Expo project is ejected (formerly: detached). You can read how to do it here. (only for Expo SDK < 43)
2. Follow steps for iOS/Android.

iOS (example setup)

1. npm install --save react-native-ble-plx
2. Enter ios folder and run pod update
3. Add NSBluetoothAlwaysUsageDescription in info.plist file. (it is a requirement since iOS 13)
4. If you want to support background mode:
   • In your application target go to Capabilities tab and enable Uses Bluetooth LE Accessories in Background Modes section.
   • Pass restoreStateIdentifier and restoreStateFunction to BleManager constructor.

Optional: iOS BLE State Restoration (Restoration subspec)

• Opt-in via the config plugin: set iosEnableRestoration: true and optionally iosRestorationIdentifier to a stable string.
• The plugin writes BlePlxRestoreIdentifier into Info.plist and injects the react-native-ble-plx/Restoration subspec into your Podfile.
• In JS, pass the same identifier to BleManager:

const manager = new BleManager({
  restoreStateIdentifier: 'com.example.myapp.bleplx',
  restoreStateFunction: (restoredState) => {
    // Rehydrate your app, reconnect devices, etc.
  },
});

• The Restoration subspec exposes a Swift adapter (BlePlxRestorationAdapter) that will register with any restoration registry present in the host app (for example, a shared BleRestorationRegistry). If no registry is present, it is a no-op.

Android (example setup)

1. npm install --save react-native-ble-plx

2. In top level build.gradle make sure that min SDK version is at least 23:

   buildscript {
       ext {
           ...
           minSdkVersion = 23
           ...

3. In build.gradle make sure to add jitpack repository to known repositories:

   allprojects {
       repositories {
         ...
         maven { url 'https://www.jitpack.io' }
       }
   }

4. In AndroidManifest.xml, add Bluetooth permissions and update <uses-sdk/>:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   
      ...
   
      <!-- Android >= 12 -->
      <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
      <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
      <!-- Android < 12 -->
      <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
      <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
      <!-- common -->
      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   
      <!-- Add this line if your application always requires BLE. More info can be found on:
          https://developer.android.com/guide/topics/connectivity/bluetooth-le.html#permissions
        -->
      <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
   
       ...

5. (Optional) In SDK 31+ You can remove ACCESS_FINE_LOCATION (or mark it as android:maxSdkVersion="30" ) from AndroidManifest.xml and add neverForLocation flag into BLUETOOTH_SCAN permissions which says that you will not use location based on scanning eg:

    <uses-permission android:name="android.permission.INTERNET" />
    <!-- Android >= 12 -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <!-- Android < 12 -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
   
       ...

   With neverForLocation flag active, you no longer need to ask for ACCESS_FINE_LOCATION in your app

Troubleshooting

Releasing

To publish a new version of the package:

1. Ensure all tests pass:

   pnpm test:package
   pnpm test:plugin

2. Commit your changes with a conventional commit message:

   git add .
   git commit -m "fix: description of fix"
   git push origin master

3. Bump version in package.json (follow semver):

   # Edit package.json to update version
   git add package.json
   git commit -m "chore: release X.Y.Z"
   git push origin master

4. Create and push git tag:

   git tag vX.Y.Z -m "Release vX.Y.Z"
   git push origin vX.Y.Z

5. Build and publish:

   pnpm run prepack
   pnpm publish --access public --no-git-checks

Commit message conventions:

• fix: - Bug fixes (patch version)
• feat: - New features (minor version)
• chore: - Maintenance tasks
• docs: - Documentation updates

Contributions

• Special thanks to @EvanBacon for supporting the expo config plugin.