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

JavaScript

JavaScript support is split into four areas: execution, return values, channels, and browser-style dialogs.

await controller.setJavaScriptMode(JavaScriptMode.unrestricted);

Disable JavaScript for untrusted content when your app does not need page scripting:

await controller.setJavaScriptMode(JavaScriptMode.disabled);

The web implementation applies a restrictive iframe sandbox when JavaScript is disabled and restores the configured sandbox when JavaScript is unrestricted.

await controller.runJavaScript('document.body.classList.add("ready")');
final value = await controller.runJavaScriptReturningResult(
'JSON.stringify({title: document.title})',
);

Return-value behavior:

PlatformReturn behavior
AndroidUses Android WebView evaluation result.
iOS/macOSUses WebKit evaluation; unsupported native values may throw.
WindowsUses WebView2 script execution and decodes returned values.
LinuxUses WebKitGTK and decodes JSON-marked results where needed.
OHOSUses ArkWeb evaluateJavascript; JSON is decoded when possible.
WebUses iframe eval for same-origin content and JSON serialization.

null and undefined are rejected by runJavaScriptReturningResult.

await controller.addJavaScriptChannel(
'Checkout',
onMessageReceived: (JavaScriptMessage message) {
debugPrint('Checkout event: ${message.message}');
},
);

Page JavaScript:

Checkout.postMessage(JSON.stringify({ type: 'loaded' }));

Remove a channel when it is no longer needed:

await controller.removeJavaScriptChannel('Checkout');
await controller.setOnConsoleMessage((JavaScriptConsoleMessage message) {
debugPrint('[${message.level.name}] ${message.message}');
});

Android, iOS, macOS, Windows, Linux, OHOS, and same-origin web content support console message callbacks.

await controller.setOnJavaScriptAlertDialog((request) async {
debugPrint('alert from ${request.url}: ${request.message}');
});
await controller.setOnJavaScriptConfirmDialog((request) async {
return request.message == 'Continue?';
});
await controller.setOnJavaScriptTextInputDialog((request) async {
return request.defaultText ?? '';
});

Dialog support by platform:

PlatformalertconfirmpromptNotes
AndroidSupportedSupportedSupportedNative WebChromeClient bridge.
iOS/macOSSupportedSupportedSupportedWebKit UI delegate bridge.
WindowsSupportedSupportedSupportedWebView2 JavaScript dialog bridge.
LinuxSupportedSupportedSupportedWebKitGTK dialog events.
OHOSSupportedSupportedSupportedArkWeb WebChromeClient bridge.
WebSame-origin onlySame-origin onlySame-origin onlyconfirm and prompt callbacks must complete synchronously.

On web, confirm and prompt are browser-synchronous APIs. Return a SynchronousFuture from those callbacks if you need deterministic behavior:

await controller.setOnJavaScriptConfirmDialog((request) {
return SynchronousFuture<bool>(true);
});

Browser iframes block direct scripting of cross-origin pages. On web, these APIs require content that the host page can access:

  • runJavaScript
  • runJavaScriptReturningResult
  • addJavaScriptChannel
  • setOnConsoleMessage
  • JavaScript dialog hooks
  • scroll position reads and writes

Use loadHtmlString, same-origin URLs, or fetch-backed loadRequest when you need those features in Flutter Web.