@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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-wifi` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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()
• isNetworkSaved(...)
• shareNetwork(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

WiFi plugin for managing device WiFi connectivity

addNetwork(...)

addNetwork(options: AddNetworkOptions) => Promise<void>

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

connect(...)

connect(options: ConnectOptions) => Promise<void>

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

disconnect(...)

disconnect(options?: DisconnectOptions | undefined) => Promise<void>

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

getAvailableNetworks()

getAvailableNetworks() => Promise<GetAvailableNetworksResult>

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

Returns: Promise<GetAvailableNetworksResult>

Since: 7.0.0

getIpAddress()

getIpAddress() => Promise<GetIpAddressResult>

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

Returns: Promise<GetIpAddressResult>

Since: 7.0.0

getRssi()

getRssi() => Promise<GetRssiResult>

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

Returns: Promise<GetRssiResult>

Since: 7.0.0

getSsid()

getSsid() => Promise<GetSsidResult>

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

Returns: Promise<GetSsidResult>

Since: 7.0.0

getWifiInfo()

getWifiInfo() => Promise<WifiInfo>

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

isEnabled()

isEnabled() => Promise<IsEnabledResult>

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

Returns: Promise<IsEnabledResult>

Since: 7.0.0

startScan()

startScan() => Promise<void>

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

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

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

requestPermissions(...)

requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>

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

addListener('networksScanned', ...)

addListener(eventName: 'networksScanned', listenerFunc: () => void) => Promise<PluginListenerHandle>

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

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 7.0.0

isNetworkSaved(...)

isNetworkSaved(options: IsNetworkSavedOptions) => Promise<IsNetworkSavedResult>

Check whether a network with the given SSID has already been saved/configured by this app. On Android SDK 30+, this checks the app's Wi-Fi network suggestions. On older Android (including SDK 29), this checks the system's configured networks list. On iOS, this checks the hotspot configurations managed by this app. Use this to decide whether to call addNetwork() (first time) or connect() (already saved).

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | -------------------------------------- | | options | IsNetworkSavedOptions | - Options containing the SSID to check |

Returns: Promise<IsNetworkSavedResult>

Since: 8.2.0

shareNetwork(...)

shareNetwork(options?: ShareNetworkOptions | undefined) => Promise<ShareNetworkResult>

Share Wi-Fi network credentials using platform-native sharing flows.

On Android 10+, this uses Wi-Fi Easy Connect (DPP). When dppUri is provided, the system provisions credentials to the target device. Otherwise, it opens the system UI to share the current or specified network (optionally via QR code when ssid and password are provided).

On iOS 26.2+, this uses the Wi-Fi Infrastructure framework with a paired AccessorySetupKit accessory. The host app must pair the accessory first and pass its bluetoothIdentifier or accessoryIdentifier. The app also needs the com.apple.developer.wifi-infrastructure entitlement.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | ----------------- | | options | ShareNetworkOptions | - Sharing options |

Returns: Promise<ShareNetworkResult>

Since: 8.4.0

getPluginVersion()

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

Get the native plugin version.

Returns: Promise<{ version: string; }>

Since: 7.0.0

Interfaces

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> |

IsNetworkSavedResult

Result from isNetworkSaved()

| Prop | Type | Description | Since | | ------------- | -------------------- | ----------------------------------------------------------------- | ----- | | isSaved | boolean | Whether the network has already been saved/configured by this app | 8.2.0 |

IsNetworkSavedOptions

Options for checking whether a network is saved

| Prop | Type | Description | Since | | ---------- | ------------------- | -------------------------------- | ----- | | ssid | string | The SSID of the network to check | 8.2.0 |

ShareNetworkResult

Result from shareNetwork()

| Prop | Type | Description | Since | | ------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----- | | started | boolean | Whether the platform sharing flow was started or completed. | 8.4.0 | | authorizationState | WifiSharingAuthorizationState | iOS: Authorization state after requestAuthorization, when requested. | 8.4.0 | | askToShareState | WifiSharingAskState | iOS: Result of askToShare when requested. | 8.4.0 |

ShareNetworkOptions

Options for sharing Wi-Fi network credentials

| Prop | Type | Description | Default | Since | | -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | dppUri | string | Android: Wi-Fi Easy Connect (DPP) URI from the target device. When provided, launches the system UI to provision Wi-Fi credentials to that device. | | 8.4.0 | | ssid | string | Network SSID to share via QR code on Android. When omitted, the system uses the currently connected network when possible. | | 8.4.0 | | password | string | Network password for QR code sharing on Android. Required when sharing a specific WPA/WPA2/WPA3 network via QR code. iOS does not allow reading saved Wi-Fi passwords from the system. | | 8.4.0 | | bluetoothIdentifier | string | iOS 26.2+: Bluetooth identifier of a paired AccessorySetupKit accessory. Required for Wi-Fi Infrastructure network sharing on iOS unless accessoryIdentifier is set. | | 8.4.0 | | accessoryIdentifier | string | iOS 26.2+: Accessory UUID from AccessorySetupKit. Alternative lookup key when bluetoothIdentifier is unavailable. | | 8.4.0 | | requestAuthorization | boolean | iOS 26.2+: Request initial Wi-Fi network sharing authorization for the accessory. | false | 8.4.0 | | askToShare | boolean | iOS 26.2+: Prompt the user to share the current Wi-Fi network with the accessory. | true | 8.4.0 |

Type Aliases

PermissionState

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

WifiSharingAuthorizationState

Authorization state returned by iOS Wi-Fi Infrastructure sharing

'authorized' | 'denied' | 'notDetermined' | 'unsupported'

WifiSharingAskState

Result state returned by iOS Wi-Fi Infrastructure askToShare()

'shared' | 'declined' | 'cancelled' | 'notNeeded' | 'unsupported'

Enums

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 |