How to connect to a BLE device using this Capacitor plugin?

Use BleClient.connect() after requesting a device with requestDevice(). The README provides a full example with heart rate monitoring, including connection, reading characteristics, and handling disconnections with callbacks.

Capacitor Bluetooth LE vs Cordova BLE plugins: which is better?

This plugin is optimized for Capacitor with Web Bluetooth API alignment, offering better integration for modern hybrid apps. Cordova plugins like cordova-plugin-bluetoothle might have broader legacy support but lack this consistent cross-platform API.

Does this plugin support background BLE operations on iOS?

Yes, by adding 'bluetooth-central' to UIBackgroundModes in Info.plist, as specified in the iOS setup instructions. This enables BLE interactions when the app is in the background, though it requires manual configuration.

How to scan for BLE devices without location permissions on Android 12?

Set androidNeverForLocation to true during initialization and update AndroidManifest.xml with BLUETOOTH_SCAN permission and neverForLocation flag, as detailed in the optional Android 12 section. Note that this may filter some BLE beacons.

Can I use this with Vue or React in an Ionic app?

Yes, the plugin is framework-agnostic and example applications are provided for Ionic/React, Angular, and Vue (via Quasar), demonstrating integration with various frontend frameworks and Capacitor.

What happens if Bluetooth is disabled on a user's device?

The plugin provides methods like isEnabled() and requestEnable() (Android only) to check and prompt users, with startEnabledNotifications() for state changes. On iOS, users may need to enable Bluetooth via app settings if initially declined.

Bluetooth-le — Capacitor BLE Plugin

What is Bluetooth-le?

@capacitor-community/bluetooth-le is a Capacitor plugin that enables Bluetooth Low Energy (BLE) communication in cross-platform applications. It provides a unified JavaScript API for discovering, connecting to, and interacting with BLE devices across web, Android, and iOS platforms, solving the problem of platform-specific BLE implementations.

Target Audience

Mobile and web developers building Capacitor-based applications that need to communicate with BLE devices such as fitness trackers, medical devices, IoT sensors, or smart peripherals.

Value Proposition

Developers choose this plugin because it offers a consistent, Web Bluetooth API-aligned interface across all supported platforms, reducing development complexity and eliminating the need to write separate native code for each platform's Bluetooth stack.

Capacitor plugin for Bluetooth Low Energy

Use Cases

Best For

Building fitness apps that connect to heart rate monitors and activity trackers
Developing IoT applications that communicate with BLE sensors and devices
Creating medical or health monitoring apps that interface with BLE medical devices
Building smart home apps that control BLE-enabled appliances and peripherals
Developing cross-platform apps that need consistent BLE functionality on web, iOS, and Android
Prototyping BLE-enabled applications quickly with a unified API

Not Ideal For

Projects requiring Bluetooth Classic or Serial communication, as it only supports BLE
Apps that need to act as a BLE peripheral (server), since it only supports the central role
Development workflows relying heavily on iOS simulators, because Bluetooth is unsupported there
Web applications needing full, unflagged BLE scanning capabilities, as some features are behind browser flags

Pros & Cons

Pros

Cross-Platform Consistency

Provides a unified API aligned with the Web Bluetooth standard, working seamlessly on web, Android, and iOS, reducing the need for platform-specific code as emphasized in the philosophy.

Comprehensive Feature Set

Supports all essential BLE operations including scanning, connecting, service discovery, read/write, and notifications, with detailed examples like heart rate monitoring in the README.

Platform-Specific Enhancements

Includes Android bonding support and iOS background mode configuration via Info.plist edits, allowing access to native capabilities while maintaining cross-platform consistency.

Active Maintenance and Documentation

Maintained until 2026 with CI checks, versioned documentation for multiple Capacitor releases, and example apps for Ionic/React, Angular, and Vue frameworks.

Cons

Web Platform Limitations

Key methods like requestLEScan are behind flags in most browsers, and features such as getMtu and readRssi are unavailable on web, limiting true cross-platform parity as shown in the platform support table.

iOS Simulator Incompatibility

Cannot test BLE functionality on iOS simulators; developers must use physical devices, which the README explicitly warns can slow development and testing cycles.

Complex Android 12+ Permissions

To avoid location permissions on Android 12+, developers must manually update manifest files and set androidNeverForLocation flags, adding setup complexity compared to older versions.

Central Role Only

Lacks support for the peripheral role, requiring separate plugins for apps that need to advertise as BLE devices, as admitted in the README with links to alternatives.

Frequently Asked Questions

What is Bluetooth-le?

Target Audience

Mobile and web developers building Capacitor-based applications that need to communicate with BLE devices such as fitness trackers, medical devices, IoT sensors, or smart peripherals.

Value Proposition

Use Cases

Best For

Building fitness apps that connect to heart rate monitors and activity trackers
Developing IoT applications that communicate with BLE sensors and devices
Creating medical or health monitoring apps that interface with BLE medical devices
Building smart home apps that control BLE-enabled appliances and peripherals
Developing cross-platform apps that need consistent BLE functionality on web, iOS, and Android
Prototyping BLE-enabled applications quickly with a unified API

Not Ideal For

Projects requiring Bluetooth Classic or Serial communication, as it only supports BLE
Apps that need to act as a BLE peripheral (server), since it only supports the central role
Development workflows relying heavily on iOS simulators, because Bluetooth is unsupported there
Web applications needing full, unflagged BLE scanning capabilities, as some features are behind browser flags

Pros & Cons

Pros

Cross-Platform Consistency

Provides a unified API aligned with the Web Bluetooth standard, working seamlessly on web, Android, and iOS, reducing the need for platform-specific code as emphasized in the philosophy.

Comprehensive Feature Set

Supports all essential BLE operations including scanning, connecting, service discovery, read/write, and notifications, with detailed examples like heart rate monitoring in the README.

Platform-Specific Enhancements

Includes Android bonding support and iOS background mode configuration via Info.plist edits, allowing access to native capabilities while maintaining cross-platform consistency.

Active Maintenance and Documentation

Maintained until 2026 with CI checks, versioned documentation for multiple Capacitor releases, and example apps for Ionic/React, Angular, and Vue frameworks.

Cons

Web Platform Limitations

iOS Simulator Incompatibility

Cannot test BLE functionality on iOS simulators; developers must use physical devices, which the README explicitly warns can slow development and testing cycles.

Complex Android 12+ Permissions

To avoid location permissions on Android 12+, developers must manually update manifest files and set androidNeverForLocation flags, adding setup complexity compared to older versions.

Central Role Only

Lacks support for the peripheral role, requiring separate plugins for apps that need to advertise as BLE devices, as admitted in the README with links to alternatives.

Frequently Asked Questions

Bluetooth-le

What is Bluetooth-le?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Bluetooth-le

What is Bluetooth-le?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?