Configure WebView

WebViewConfig is applied when rememberWebViewController() creates the native view. Changing the object later does not reconfigure an existing instance.

Start with the scenario

Decide whether a screen is persistent, guest-only, account-isolated, or needs a managed desktop data directory before choosing a platform config.

On this page

1. Choose by scenario
2. Common options
3. Platform options
4. Creation and recreation
5. API reference

Choose by scenario

Need	Recommended setting	Result
Persistent signed-in browsing	WebViewConfig()	Platform default persistent storage.
Guest or sensitive preview	iOS/macOS NON_PERSISTENT	No persistent WebKit website data.
Separate Android accounts	A distinct AndroidX Profile per view	Cookies, DOM storage, permissions, workers, and cache follow the profile boundary.
Managed desktop data	JVM dataDir (and Linux cacheDir)	Native backend stores data in application-controlled paths.
Identify the host app	userAgent	Creation-time User-Agent override.

Instance-level configuration

One config describes one native WebView creation; it is not a runtime settings panel.

Platform fields vary

Put WebViewPlatformConfig values in the matching source set because expect/actual fields differ.

Common options

commonMain can safely set userAgent; null keeps the platform default.

val controller = rememberWebViewController(
    url = "https://help.example.com",
    config = WebViewConfig(userAgent = "ExampleApp/1.0"),
)

JVM User-Agent behavior

On JVM the value replaces the current OS backend User-Agent. The backend settings are selected for the operating system that is actually running.

Platform options

Android profiles

config = WebViewConfig(platform = WebViewPlatformConfig(profile = profile))

When profile is non-null, check AndroidX WebViewFeature.MULTI_PROFILE first; unsupported runtimes throw UnsupportedOperationException. null uses the default profile.

iOS website data

config = WebViewConfig(platform = WebViewPlatformConfig(
    websiteDataStore = WebsiteDataStore.NON_PERSISTENT,
))

JVM directories

config = WebViewConfig(platform = WebViewPlatformConfig(
    windowSetting = WebViewPlatformConfig.Windows(dataDir = "C:/ExampleApp/webview"),
    linuxSetting = WebViewPlatformConfig.Linux(
        dataDir = "/var/lib/example-app/webview",
        cacheDir = "/var/cache/example-app/webview",
    ),
))

Backend	Fields	Default
Windows / WebView2	windowSetting.dataDir	${java.io.tmpdir}/wvbridge
Linux / WebKitGTK	linuxSetting.dataDir, cacheDir	${java.io.tmpdir}/wvbridge/data, ${java.io.tmpdir}/wvbridge/cache
macOS / WKWebView	macOSSetting.websiteDataStore	DEFAULT

Creation and recreation

WebViewConfig ──> rememberWebViewController(config) ──> native WebView
      │                                      │
      └── mutate later ─────────────────────┘  no reconfiguration

Create a new controller/WebView lifecycle when changing account, storage mode, or data directory. Android currently keys remembering by userAgent; iOS and JVM use the whole config.

API reference

Dokka See WebViewConfig and WebViewPlatformConfig, rememberWebViewController, and the complete API.