Skip to content
WebView AllWebView All
Documentation for version 1.2.x; select latest for up-to-date APIs.

Navigation

NavigationDelegate collects navigation callbacks and installs them into the platform implementation through WebViewController.setNavigationDelegate.

await controller.setNavigationDelegate(
NavigationDelegate(
onNavigationRequest: (NavigationRequest request) {
if (request.url.startsWith('myapp://')) {
return NavigationDecision.prevent;
}
return NavigationDecision.navigate;
},
onPageStarted: (String url) {},
onProgress: (int progress) {},
onPageFinished: (String url) {},
onUrlChange: (UrlChange change) {},
onWebResourceError: (WebResourceError error) {},
onHttpError: (HttpResponseError error) {},
onHttpAuthRequest: (HttpAuthRequest request) {},
onSslAuthError: (SslAuthError error) {},
),
);

onNavigationRequest can prevent main-frame and sub-frame navigations when the engine reports them. The callback may return synchronously or as a Future.

onNavigationRequest: (NavigationRequest request) async {
final uri = Uri.tryParse(request.url);
if (uri == null) {
return NavigationDecision.prevent;
}
return uri.host.endsWith('example.com')
? NavigationDecision.navigate
: NavigationDecision.prevent;
}

Some platforms also invoke the callback for controller-initiated loads. Treat it as a central policy hook.

CallbackMeaning
onPageStartedMain-frame load started.
onProgressEngine-reported load progress from 0 to 100 when available.
onPageFinishedMain-frame load completed.
onUrlChangeVisible or logical URL changed.

The web implementation reports logical URLs for loadHtmlString and fetch-backed loadRequest, because those loads are rendered through srcdoc or data: URLs internally.

onWebResourceError reports network, TLS, file, policy, and engine failures:

onWebResourceError: (WebResourceError error) {
debugPrint('code=${error.errorCode}');
debugPrint('type=${error.errorType}');
debugPrint('mainFrame=${error.isForMainFrame}');
debugPrint('url=${error.url}');
}

Platform-specific subclasses add detail:

PlatformSubclassExtra fields
AndroidAndroidWebResourceErrorfailingUrl is deprecated; use url.
iOS/macOSWebKitWebResourceErrorWraps WebKit/NSError mapping.
WindowsWindowsWebResourceErrorMaps WebView2 WebErrorStatus.
LinuxLinuxWebResourceErrorMaps WebKitGTK error types.
OHOSOhosWebResourceErrorMaps ArkWeb error codes.
WebWebResourceErrorUsed for fetch failures.

onHttpError reports HTTP responses with status code 400 or greater when the engine exposes the response:

onHttpError: (HttpResponseError error) {
final status = error.response?.statusCode;
final headers = error.response?.headers;
}

Windows, Linux, OHOS, iOS, macOS, and web report HTTP errors. Android reports them through the official Android implementation.

On web, onHttpError only fires for fetch-backed loads. A simple cross-origin iframe navigation is owned by the browser and does not expose response headers to the host page.

onHttpAuthRequest: (HttpAuthRequest request) {
request.onProceed(
const WebViewCredential(user: 'demo', password: 'secret'),
);
}

Call exactly one response path. If you do not intend to continue, call request.onCancel().

onSslAuthError: (SslAuthError error) async {
debugPrint(error.platform.description);
await error.cancel();
}

Only call proceed() for controlled test environments. In production, a recoverable certificate error means the connection is not trustworthy.

The web platform cannot expose recoverable TLS decisions. Browser iframe APIs do not allow an embedded Flutter app to proceed past or cancel certificate errors, so WebPlatformSslAuthError.proceed() and cancel() throw UnsupportedError.

PlatformNotes
AndroidNavigation, HTTP auth, SSL auth, HTTP errors, URL changes, and resource errors are handled by the official Android package.
iOS/macOSHTTP auth supports Basic and NTLM challenges. Recoverable server trust errors can be surfaced through onSslAuthError.
WindowsWebView2 reports HTTP response errors, HTTP auth, SSL auth, and load errors through the native bridge.
LinuxWebKitGTK reports navigation requests, HTTP auth, SSL auth, permission requests, and JavaScript dialogs through an event channel.
OHOSArkWeb reports HTTP errors, HTTP auth, SSL auth, visited history updates, and request details including method and headers where available.
WebNavigation decisions are enforced for controller-initiated loads. Browser iframe navigations inside cross-origin pages are not fully observable.