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

Install

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()
• isEnabled()
• startScan()
• checkPermissions()
• requestPermissions(...)
• addListener('networksScanned', ...)
• removeAllListeners()
• 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. 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

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

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 |

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 |

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

Type Aliases

PermissionState

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

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 |