React Native Bluetooth Low Energy library
npm install @srivathsav03/react-native-ble-plxIt 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
1. Compatibility
2. Recent Changes
3. Documentation & Support
4. Configuration & Installation
5. Troubleshooting
6. Contributions
For old RN versions (<0.60) please check old README (1.x)
for the old instructions or migration guide.
| React Native | 4.0.0 |
| ------------ | ------------------ |
| 0.77.0 | :white_check_mark: |
| Expo 54 | :white_check_mark: |
Minimums: iOS 15+, Node.js 20+ (tooling).
4.0.0
- Added background BLE scanning and data collection APIs (Android) with foreground services
- Added iOS API stubs for background parity
- Updated React Native to 0.77.0 and React to 19.0.0
- Raised minimum iOS to 15 and Node.js to 20
Current version changes
All previous changes
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.
> Tested against Expo SDK 54
> This package cannot be used in the "Expo Go" app because it requires custom native code.
> First install the package with yarn, npm, pnpm, 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:
``json`
{
"expo": {
"plugins": ["@srivathsav03/react-native-ble-plx"]
}
}
Then you should build the version using native modules (e.g. with npx expo prebuild command).npx expo run:android
And install it directly into your device with .
You can find more details in the "Adding custom native code" guide.
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 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.
> Expo SDK 53 supports iOS 15+ which means NSBluetoothPeripheralUsageDescription is fully deprecated. The config plugin no longer adds it.
#### Example
`json`
{
"expo": {
"plugins": [
[
"@srivathsav03/react-native-ble-plx",
{
"isBackgroundEnabled": true,
"modes": ["peripheral", "central"],
"bluetoothAlwaysPermission": "Allow $(PRODUCT_NAME) to connect to bluetooth devices"
}
]
]
}
}
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.
1. npm install --save @srivathsav03/react-native-ble-plx
1. Enter folder and run pod update
1. Add in info.plist file. (it is a requirement since iOS 13)Capabilities
1. If you want to support background mode:
- In your application target go to tab and enable Uses Bluetooth LE Accessories inBackground Modes
section.restoreStateIdentifier
- Pass and restoreStateFunction to BleManager constructor.
1. npm install --save @srivathsav03/react-native-ble-plx
1. In top level make sure that min SDK version is at least 23:
`groovy`
buildscript {
ext {
...
minSdkVersion = 23
...
1. In build.gradle make sure to add jitpack repository to known repositories:
`groovy`
allprojects {
repositories {
...
maven { url 'https://www.jitpack.io' }
}
}
1. In AndroidManifest.xml, add Bluetooth permissions and update :
`xml
...
...
`
1. (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:
`xml
...
`
With neverForLocation flag active, you no longer need to ask for ACCESS_FINE_LOCATION` in your app
- Special thanks to @EvanBacon for supporting the expo config plugin.