Skip to content

Settings ​

WebViewSettings is immutable. Pass it to the constructor, or replace it later with updateSettings:

dart
final controller = AdvancedWebViewController(
  settings: const WebViewSettings(userAgent: 'MyApp/1.0'),
);

await controller.updateSettings(const WebViewSettings(javaScriptEnabled: false));

Options that exist on one platform only live in AndroidWebViewSettings and IOSWebViewSettings, passed as android: and ios:. The other platform ignores them, so one WebViewSettings value works on both:

dart
const WebViewSettings(
  android: AndroidWebViewSettings(passkeysEnabled: true),
  ios: IOSWebViewSettings(allowsInlineMediaPlayback: true),
);
SettingDefaultAndroidiOS
javaScriptEnabledtrueYesYes
mediaPlaybackRequiresUserGesturetrueYesCreation only
transparentBackgroundfalseYesYes
inspectablefalseYes (process-wide)Yes
textZoom100Text onlyWhole page
cacheModenormalYesloadUrl only
javaScriptCanOpenWindowsAutomaticallytrueYesYes
scrollbarsVisibletrueYesYes
overScrollEnabledtrueYesYes
pullToRefreshEnabledfalseYesYes (needs overScrollEnabled)
minimumFontSizenull (platform default)YesYes
userAgentnull (platform default)YesYes

Android-only settings ​

Passed as WebViewSettings.android. iOS ignores all of them.

SettingDefaultAndroidiOS
supportZoomtrueYesIgnored
builtInZoomControlstrueYes (pinch and double tap; needs supportZoom)Ignored
displayZoomControlsfalseYes (on-screen + / - buttons)Ignored
passkeysEnabledfalseYesIgnored (see below)
domStorageEnabledtrueYesIgnored (always on)
allowFileAccessfalseYesIgnored
allowContentAccessfalseYesIgnored
mixedContentModeneverAllowYesIgnored (WebKit blocks it)
geolocationEnabledtrueYesIgnored (system decides)
thirdPartyCookiesEnabledfalseYesIgnored (WebKit decides)
safeBrowsingEnabledtrueYes (Android 8.0+)Ignored (always on)
algorithmicDarkeningAllowedfalseYes (needs a dark app theme)Ignored (see userInterfaceStyle)

iOS-only settings ​

Passed as WebViewSettings.ios. Android ignores all of them.

SettingDefaultAndroidiOS
allowsInlineMediaPlaybackfalseIgnoredCreation only
allowsBackForwardNavigationGesturesfalseIgnoredYes
incognitofalseIgnoredCreation only
applicationNameForUserAgentnullIgnoredCreation only
contentModerecommendedIgnoredYes
allowsLinkPreviewtrueIgnoredYes
userInterfaceStyleunspecifiedIgnoredYes (light / dark sets prefers-color-scheme)

"Creation only" settings are applied when the native view is created and ignored by updateSettings on that platform.

Dark mode ​

Pages follow prefers-color-scheme. On iOS, IOSWebViewSettings.userInterfaceStyle (light / dark) fixes the appearance of that WebView, so pages that support a dark theme switch to it regardless of the system setting; the default unspecified follows the app. On Android, AndroidWebViewSettings.algorithmicDarkeningAllowed lets the WebView darken pages that have no dark theme. It only darkens while the app theme is dark (for example a DayNight theme with the system in dark mode), pages that set color-scheme: dark themselves are left alone, and it has no effect on a WebView that does not support the feature. Both are off by default, so existing apps look the same.

Android security settings ​

AndroidWebViewSettings.allowFileAccess, allowContentAccess and mixedContentMode default to the restrictive values, so a page cannot read local files or content:// providers and HTTP content is blocked on HTTPS pages. Loosen them only for content you control. mixedContentMode: alwaysAllow lets a network attacker tamper with secure pages. iOS has no equivalent settings: WebKit blocks mixed content and there is no file access switch. domStorageEnabled stays on by default, as in earlier versions.

Passkeys (WebAuthn) ​

Passkeys work only for sites whose domain is associated with your app.

  • Android: set AndroidWebViewSettings.passkeysEnabled: true and publish /.well-known/assetlinks.json with delegate_permission/common.get_login_creds, your package name and signing certificate SHA-256. Requires androidx.webkit 1.12+ and a WebView that supports WebAuthn; otherwise the setting is ignored.
  • iOS (16+): no setting is needed. Add the Associated Domains capability with webcredentials:example.com and serve /.well-known/apple-app-site-association with your app ID.
  • Passkeys of third-party identity providers (e.g. Google) and mediation: "conditional" are not supported inside a WebView.

See Platform API mapping for the native API behind each setting.

On Android, updateSettings can enable and disable passkeys on a WebView that supports WebAuthn.

Released under the MIT License.