@capgo/capacitor-wifi

Manage Wi-Fi from your Capacitor app: connect to networks, read the current SSID, IP and signal, and scan nearby networks on Android.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-wifi in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-wifi to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Connect: connect(), addNetwork() and disconnect().
• Current network: getSsid(), getIpAddress() and getWifiInfo().
• Scanning on Android: startScan(), getAvailableNetworks(), getRssi() and the networksScanned event.
• Saved networks and sharing: isNetworkSaved() and shareNetwork().
• Permissions: location permission helpers. On Android, scans, SSID, RSSI and getWifiInfo() need location permission.
• Platforms: iOS and Android. iOS uses NetworkExtension hotspot configuration, so some calls are Android only. Not available on web.

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

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.

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.

Resolves only after the device is confirmed associated with the requested SSID. On failure, rejects with a Capacitor error that includes a stable code from {@link WifiConnectionErrorCode}. Prefer error.code over parsing error.message. Specific codes are returned only when the native OS provides that reason; otherwise the plugin returns CONNECTION_FAILED.

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.

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.

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.

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

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.

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

ConnectOptions

Options for connecting to a network

DisconnectOptions

Options for disconnecting from a network

GetAvailableNetworksResult

Result from getAvailableNetworks()

Network

Represents a Wi-Fi network

GetIpAddressResult

Result from getIpAddress()

GetRssiResult

Result from getRssi()

GetSsidResult

Result from getSsid()

WifiInfo

Comprehensive WiFi information

IsEnabledResult

Result from isEnabled()

PermissionStatus

Permission status

RequestPermissionsOptions

Options for requesting permissions

PluginListenerHandle

IsNetworkSavedResult

Result from isNetworkSaved()

IsNetworkSavedOptions

Options for checking whether a network is saved

ShareNetworkResult

Result from shareNetwork()

ShareNetworkOptions

Options for sharing Wi-Fi network credentials

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