react-native-ble-plx: BLE in React Native, and the Peripheral Support It Does Not Have

What react-native-ble-plx covers, and what it refuses to cover

The README is unusually direct about scope. Supported: observing the Bluetooth adapter state, scanning for BLE devices, connecting to peripherals, discovering services and characteristics, reading and writing characteristics, observing notifications and indications, reading RSSI, negotiating MTU, background mode on iOS, and turning the device's Bluetooth adapter on. That is the central-role checklist, and it is the whole of it.

The unsupported list is the more useful half. Bluetooth Classic devices are out. So is phone-to-phone communication over BLE, because there is no peripheral support. Bonding peripherals is out, and so are beacons, which the README links to a FAQ entry. If your product plan involves an accessory that pairs through the system settings, or an iBeacon-style broadcast, this library is the wrong starting point and no amount of wrapper code changes that.

The audience follows from that split. react-native-ble-plx is for teams building a mobile app that talks to a peripheral they already have or are specifying: a sensor, a wearable, a configurable device. The library assumes the phone is the initiator and the other side answers.

How the BleManager flow actually runs

Everything routes through a BleManager instance. You construct it once, subscribe to its state, then drive a sequence: start a scan, receive device objects in the scan callback, stop the scan, connect to a device, discover its services and characteristics, then read, write or subscribe on individual characteristics.

The README's Recent Changes section for 3.2.0 documents a meaningful shift in that flow. destroyClient, cancelTransaction, setLogLevel, startDeviceScan and stopDeviceScan were changed to promises so that errors can be reported back to the React Native side. If you are reading older tutorials that call these as fire-and-forget methods, the error handling they show is out of date. The same release added Android instance checking before calling a method, so a call on a destroyed client surfaces as a visible error rather than silent failure.

On iOS, background work is not automatic. The README says to enable Uses Bluetooth LE Accessories under Background Modes in the application target's Capabilities tab, and to pass restoreStateIdentifier and restoreStateFunction to the BleManager constructor. That pair is what lets the system hand your app back its previous central state after a relaunch. Without them, background mode is a capability flag with nothing behind it.

Installing react-native-ble-plx and scanning for the first device

On a bare React Native project the README's iOS path is three steps: install the package, run pod update inside the ios folder, and add NSBluetoothAlwaysUsageDescription to Info.plist, which it notes is a requirement since iOS 13. The Android path starts the same way, then requires a minimum SDK of 23 in the top-level build.gradle.

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

For Expo, the README is explicit that this package cannot be used in the Expo Go app because it requires custom native code. You install it, which the README suggests can also be done with npx expo install, then register the config plugin.

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

After that you build a native version of the app with npx expo prebuild and install it on a device with npx expo run:android. The plugin accepts props when the defaults are not enough: isBackgroundEnabled adds the android.hardware.bluetooth_le uses-feature entry to AndroidManifest.xml, modes adds iOS UIBackgroundModes values of peripheral or central, and bluetoothAlwaysPermission sets the iOS permission string. The README warns that every prop change requires rebuilding and prebuilding the native app.

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

The README does not walk through the scanning API inline; it points to the wiki page on Bluetooth Scanning for that. So the honest first-use description ends at a built app with the right permissions declared. The call sequence itself lives in the wiki and in the example project under example/src.

The neverForLocation flag is the sharpest edge in the config

Among the plugin props, neverForLocation deserves separate attention. It maps to an Android SDK 31+ behaviour where you declare that your app never derives physical location from Bluetooth scan results, which lets you avoid the location permission on newer devices. The README attaches a warning to it: the parameter is experimental, BLE might not work, and you should test before releasing to production. It also notes that the location permission is still required on older Android devices, and that some BLE beacons get filtered out of scan results when the flag is set.

That is a genuine trade-off, not a documentation formality. An app that scans for a known peripheral by service UUID is a reasonable candidate. An app that lists every nearby device, or that depends on seeing advertising packets from beacon hardware, is not, because the filter removes exactly those results.

The other prop with real consequences is isBackgroundEnabled. It sets android.hardware.bluetooth_le as required in the manifest, which affects which devices can install the app from a store listing. Enabling background scanning is not a checkbox you flip back later without shipping a new build.

Where react-native-ble-plx stops being the right tool

The unsupported list is the failure-mode list. Classic Bluetooth is the biggest one: audio profiles, serial-port-profile style links and older accessories are simply outside the library, and teams that discover this after choosing it usually end up rewriting the transport layer. Peripheral support is the second: if two phones must talk to each other, or your app must advertise a service, this library has no path for it. Bonding is the third, which matters for peripherals that expect a system-level pairing step before any GATT traffic.

Version compatibility is a quieter constraint. The README's compatibility table is short: React Native 0.74.1, React Native 0.69.6 and Expo 51 are marked as supported against 3.1.2, and the README directs anyone on React Native below 0.60 to the old 1.x README and migration guide. A table that narrow means you should check your own version before planning work around the library, not after.

Finally, the maintainers sell integration services through a link in the README. That is a legitimate business model, but it tells you something about the support expectation: this is a library with a commercial consultancy behind it, and the wiki plus the example app are the primary self-serve resources.

react-native-ble-manager and the difference in approach

The most common comparison is react-native-ble-manager. Both are React Native BLE libraries aimed at central-role work, and both expose scanning, connection and characteristic operations. The difference is in the API surface and the surrounding packaging rather than in what the radios can do.

react-native-ble-plx is built around a BleManager object with a promise-oriented call style, and it ships an Expo config plugin through app.plugin.js and the plugin directory, which is why the README can tell Expo users exactly which props to set in app.json. It also carries a documented compatibility table and a versioned changelog going back before 3.0.0.

react-native-ble-manager is the alternative to look at if you want a different API shape or if the ble-plx compatibility table excludes your React Native version. The honest framing is that the two are close substitutes for central-role apps, and the deciding factors are the API you prefer, the Expo plugin story, and which one currently covers your React Native release. Neither one gives you Bluetooth Classic or peripheral mode.

Maintenance, licence and what upgrading costs

The repository is not archived. The most recent push was on 2026-03-09, and the most recent release is v3.5.1 from 2026-02-18. Before that, v3.5.0 landed on 2025-02-11 and v3.4.0 on 2025-01-08, so the gap between v3.5.0 and v3.5.1 is about a year, and the two releases before it came a month apart. That cadence is worth knowing if you plan to depend on upstream fixes for a specific Android or iOS version.

The package version in package.json is 3.5.1, matching the release tag. The project is licensed under Apache-2.0, which permits commercial and closed-source use and includes an explicit patent grant; the repository's LICENSE file is the authoritative text. Apache-2.0 does not oblige you to publish your app's source, but it does require that you preserve the licence and notice files for the parts you redistribute. That is a general property of the licence, not advice about your situation.

Upgrade cost concentrates in two places. Native configuration changes require a prebuild and a rebuild, as the README states for plugin props. API changes require reading CHANGELOG.md, because the 3.2.0 entry shows that method signatures have moved from callbacks to promises within the 3.x line. Pinning to a known version and reading the changelog before bumping is cheaper than discovering a signature change at runtime.

Editorial conclusion

Adopt react-native-ble-plx if your app is a BLE central on iOS and Android and you accept the Expo custom-native-code workflow: install it, add the config plugin to app.json, then prebuild. Do not adopt it if you need Bluetooth Classic, peripheral mode, bonding or beacon parsing, because the README lists all four as unsupported. Verify first that your React Native version appears in the compatibility table, and that your minimum Android SDK is 23.

Frequently asked questions

Official sources

1. dotintent/react-native-ble-plx on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases