@capgo/capacitor-wifi

Manage WiFi connectivity for your Capacitor app

Why Capacitor WiFi?

A free and powerful WiFi management plugin with modern platform support:

- Network management - Connect, disconnect, and add WiFi networks programmatically
- Network scanning - Discover available WiFi networks (Android only)
- Network info - Get SSID, IP address, and signal strength (RSSI)
- Modern APIs - Uses NetworkExtension (iOS) and handles Android 10+ restrictions
- Cross-platform - Consistent API across iOS and Android

Perfect for IoT apps, network diagnostic tools, and smart home applications.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/wifi/

Compatibility

| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\.\ | v8.\.\ | ✅ |
| v7.\.\ | v7.\.\ | On demand |
| v6.\.\ | v6.\.\ | ❌ |
| v5.\.\ | v5.\.\ | ❌ |

> Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

``bash
npm install @capgo/capacitor-wifi
npx cap sync
`

Requirements

- iOS: Requires location permission (NSLocationWhenInUseUsageDescription in Info.plist) to access WiFi information. Uses NetworkExtension framework.
- Android: Requires location permissions. Network scanning and RSSI available on Android only. Android 10+ uses system dialogs for adding networks.

API

* addNetwork(...)
* connect(...)
* disconnect(...)
* getAvailableNetworks()
* getIpAddress()
* getRssi()
* getSsid()
* getWifiInfo()
* isEnabled()
* startScan()
* checkPermissions()
* requestPermissions(...)
* addListener('networksScanned', ...)
* removeAllListeners()
* getPluginVersion()
* Interfaces
* Type Aliases
* Enums

WiFi plugin for managing device WiFi connectivity

$3

`typescript
addNetwork(options: AddNetworkOptions) => Promise
`

Show a system dialog to add a Wi-Fi network to the device.
On Android SDK 30+, this opens the system Wi-Fi settings with the network pre-filled.
On iOS, this connects to the network directly.

| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
| options | AddNetworkOptions | - Network configuration options |

Since: 7.0.0

--------------------

$3

`typescript
connect(options: ConnectOptions) => Promise
`

Connect to a Wi-Fi network.
On Android, this creates a temporary connection that doesn't route traffic through the network by default.
Set autoRouteTraffic to true to bind app traffic to the connected network (useful for local/device-hosted APs).
For a persistent connection on Android, use addNetwork() instead.
On iOS, this creates a persistent connection.

| Param | Type | Description |
| ------------- | --------------------------------------------------------- | -------------------- |
| options | ConnectOptions | - Connection options |

Since: 7.0.0

--------------------

$3

`typescript
disconnect(options?: DisconnectOptions | undefined) => Promise
`

Disconnect from the current Wi-Fi network.
On iOS, only disconnects from networks that were added via this plugin.

| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ----------------------------- |
| options | DisconnectOptions | - Optional disconnect options |

Since: 7.0.0

--------------------

$3

`typescript
getAvailableNetworks() => Promise
`

Get a list of available Wi-Fi networks from the last scan.
Only available on Android.

Returns: Promise<GetAvailableNetworksResult>

Since: 7.0.0

--------------------

$3

`typescript
getIpAddress() => Promise
`

Get the device's current IP address.
Available on both Android and iOS.

Returns: Promise<GetIpAddressResult>

Since: 7.0.0

--------------------

$3

`typescript
getRssi() => Promise
`

Get the received signal strength indicator (RSSI) of the current network in dBm.
Only available on Android.

Returns: Promise<GetRssiResult>

Since: 7.0.0

--------------------

$3

`typescript
getSsid() => Promise
`

Get the service set identifier (SSID) of the current network.
Available on both Android and iOS.

Returns: Promise<GetSsidResult>

Since: 7.0.0

--------------------

$3

`typescript
getWifiInfo() => Promise
`

Get comprehensive information about the currently connected WiFi network.
This method provides detailed network information including SSID, BSSID, IP address,
frequency, link speed, and signal strength in a single call.
On iOS, some fields may not be available and will be undefined.

Returns: Promise<WifiInfo>

Since: 7.0.0

--------------------

$3

`typescript
isEnabled() => Promise
`

Check if Wi-Fi is enabled on the device.
Only available on Android.

Returns: Promise<IsEnabledResult>

Since: 7.0.0

--------------------

$3

`typescript
startScan() => Promise
`

Start scanning for Wi-Fi networks.
Only available on Android.
Results are delivered via the 'networksScanned' event listener.
Note: May fail due to system throttling or hardware issues.

Since: 7.0.0

--------------------

$3

`typescript
checkPermissions() => Promise
`

Check the current permission status for location access.
Location permission is required for Wi-Fi operations on both platforms.

Returns: Promise<PermissionStatus>

Since: 7.0.0

--------------------

$3

`typescript
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise
`

Request location permissions from the user.
Location permission is required for Wi-Fi operations on both platforms.

| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------------- | ------------------------------------- |
| options | RequestPermissionsOptions | - Optional permission request options |

Returns: Promise<PermissionStatus>

Since: 7.0.0

--------------------

$3

`typescript
addListener(eventName: 'networksScanned', listenerFunc: () => void) => Promise
`

Add a listener for the 'networksScanned' event.
Only available on Android.
This event is fired when Wi-Fi scan results are available.

| Param | Type | Description |
| ------------------ | ------------------------------ | ------------------------------------ |
| eventName | 'networksScanned' | - The event name ('networksScanned') |
| listenerFunc | () => void | - The callback function to execute |

Returns: Promise<PluginListenerHandle>

Since: 7.0.0

--------------------

$3

`typescript
removeAllListeners() => Promise
`

Remove all listeners for this plugin.

Since: 7.0.0

--------------------

$3

`typescript
getPluginVersion() => Promise<{ version: string; }>
`

Get the native plugin version.

Returns: Promise<{ version: string; }>

Since: 7.0.0

--------------------

$3


#### AddNetworkOptions

Options for adding a network

| Prop | Type | Description | Default | Since |
| ------------------ | ------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----- |
| ssid | string | The SSID of the network to add | | 7.0.0 |
| password | string | The password for the network (optional for open networks) | | 7.0.0 |
| isHiddenSsid | boolean | Whether the network is hidden (Android only) | false | 7.0.0 |
| securityType | NetworkSecurityType | The security type of the network (Android only) | NetworkSecurityType.WPA2_PSK | 7.0.0 |


#### ConnectOptions

Options for connecting to a network

| Prop | Type | Description | Default | Since |
| ---------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| ssid | string | The SSID of the network to connect to | | 7.0.0 |
| password | string | The password for the network (optional for open networks) | | 7.0.0 |
| isHiddenSsid | boolean | Whether the network is hidden (Android only) | false | 7.0.0 |
| autoRouteTraffic | boolean | Whether to automatically route app traffic through the connected Wi-Fi network (Android only) When enabled, it binds the app process to the connected network using ConnectivityManager.bindProcessToNetwork() This is useful for connecting to local/device-hosted APs (e.g., ESP32, IoT devices) that don't have internet access. | false | 7.0.0 |


#### DisconnectOptions

Options for disconnecting from a network

| Prop | Type | Description | Since |
| ---------- | ------------------- | ----------------------------------------------------- | ----- |
| ssid | string | The SSID of the network to disconnect from (optional) | 7.0.0 |


#### GetAvailableNetworksResult

Result from getAvailableNetworks()

| Prop | Type | Description | Since |
| -------------- | ---------------------- | -------------------------- | ----- |
| networks | Network[] | List of available networks | 7.0.0 |


#### Network

Represents a Wi-Fi network

| Prop | Type | Description | Since |
| ------------------- | ---------------------------------- | ------------------------------------------------------------------- | ----- |
| ssid | string | The SSID of the network | 7.0.0 |
| rssi | number | The signal strength in dBm | 7.0.0 |
| securityTypes | NetworkSecurityType[] | The security types supported by this network (Android SDK 33+ only) | 7.0.0 |


#### GetIpAddressResult

Result from getIpAddress()

| Prop | Type | Description | Since |
| --------------- | ------------------- | ----------------------- | ----- |
| ipAddress | string | The device's IP address | 7.0.0 |


#### GetRssiResult

Result from getRssi()

| Prop | Type | Description | Since |
| ---------- | ------------------- | -------------------------- | ----- |
| rssi | number | The signal strength in dBm | 7.0.0 |


#### GetSsidResult

Result from getSsid()

| Prop | Type | Description | Since |
| ---------- | ------------------- | ------------------------------- | ----- |
| ssid | string | The SSID of the current network | 7.0.0 |


#### WifiInfo

Comprehensive WiFi information

| Prop | Type | Description | Since |
| -------------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- |
| ssid | string | The SSID (network name) of the current network | 7.0.0 |
| bssid | string | The BSSID (MAC address) of the access point. Not available on iOS. | 7.0.0 |
| ip | string | The device's IP address on the network | 7.0.0 |
| frequency | number | The network frequency in MHz. Not available on iOS. | 7.0.0 |
| linkSpeed | number | The connection speed in Mbps. Not available on iOS. | 7.0.0 |
| signalStrength | number | The signal strength (0-100). Calculated from RSSI on Android. Not available on iOS. | 7.0.0 |


#### IsEnabledResult

Result from isEnabled()

| Prop | Type | Description | Since |
| ------------- | -------------------- | ------------------------ | ----- |
| enabled | boolean | Whether Wi-Fi is enabled | 7.0.0 |


#### PermissionStatus

Permission status

| Prop | Type | Description | Since |
| -------------- | ----------------------------------------------------------- | ------------------------- | ----- |
| location | PermissionState | Location permission state | 7.0.0 |


#### RequestPermissionsOptions

Options for requesting permissions

| Prop | Type | Description | Since |
| ----------------- | ------------------------- | ---------------------- | ----- |
| permissions | 'location'[] | Permissions to request | 7.0.0 |


#### PluginListenerHandle

| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |

$3


#### PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

$3


#### NetworkSecurityType

| Members | Value | Description | Since |
| ----------------------------- | --------------- | ------------------------------ | ----- |
| OPEN | 0 | Open network with no security | 7.0.0 |
| WEP | 1 | WEP security | 7.0.0 |
| WPA2_PSK | 2 | WPA/WPA2 Personal (PSK) | 7.0.0 |
| EAP | 3 | WPA/WPA2/WPA3 Enterprise (EAP) | 7.0.0 |
| SAE | 4 | WPA3 Personal (SAE) | 7.0.0 |
| WPA3_ENTERPRISE | 5 | WPA3 Enterprise | 7.0.0 |
| WPA3_ENTERPRISE_192_BIT | 6 | WPA3 Enterprise 192-bit mode | 7.0.0 |
| PASSPOINT | 7 | Passpoint network | 7.0.0 |
| OWE | 8 | Enhanced Open (OWE) | 7.0.0 |
| WAPI_PSK | 9 | WAPI PSK | 7.0.0 |
| WAPI_CERT` | 10 | WAPI Certificate | 7.0.0 |