[Feature]: Preload network connectivity check before loading remote WebView URL

[harkelino]

Description

A pre-flight connectivity check would allow developers to show a local offline page reliably before attempting to load the remote URL.

Platforms

• iOS
• Android
• Web

Request or proposed solution

Summary:

When using server.url to load a remote web app in Capacitor, the iOS WebView may show a blank screen on cold launch if the device has no internet connection. The existing server.errorPath option is unreliable because WebKit does not always trigger it on DNS or TLS failures. A pre-flight connectivity check would allow developers to show a local offline page reliably before attempting to load the remote URL.

Problem:

• Apps that load a remote site via server.url are entirely dependent on network connectivity.
• On iOS, if the device is offline when the app first launches, WKWebView may hang and never render content.
• errorPath only triggers on actual network errors and does not reliably handle DNS or TLS stalls.
• Developers have no current way to show a fallback UI (offline.html) on cold start.

Proposed Solution:

Introduce a configuration option, or pre-flight API, that allows the app to:

• Check network connectivity before the WebView loads the remote URL.
• Return a boolean or fire a callback indicating whether the network is available.
• If no connection, optionally render offline.html immediately, avoiding the blank screen.

Optional enhancements:

• Configurable timeout for the connectivity check.
• Automatic retry or fallback mechanism.
• Support for both iOS and Android.

Benefits:

• Prevents blank screens on first launch when offline.
• Improves UX for apps that rely on remote URLs.
• Makes server.errorPath more predictable.
• Backwards-compatible: apps without the feature continue to behave as they do today.

Example Use Case:

A Capacitor app loading a Next.js web app (server.url = "https://example.com").
App is launched while the device is in airplane mode.
Currently: blank screen, no feedback.

With this feature: local offline page (offline.html) is displayed immediately, user can retry when online.

Alternatives

No response

Additional Information

No response