compose-webview

1.9.0indexed

Feature-rich WebView wrapper integrating native UI, offering promise-based JSBridge, type-safe serialization, reactive state management, lifecycle handling, request interception, dark mode, and file uploads.

AndroidJSJVMNativeWasm·parkwoocheol/compose-webview

Stars

Used by

dependents

Health

/ 100

ComposeWebView

A powerful, flexible, and feature-rich WebView wrapper for Jetpack Compose and Compose Multiplatform (Android, iOS, Desktop, Web).

Supports Android, iOS, Desktop (JVM), and Web (JS) with a unified API.

Documentation

📘 Full Documentation: https://parkwoocheol.github.io/compose-webview/

Visit the documentation site for comprehensive guides, API references, and advanced usage examples.

Features

Requirements

Android API 24+
iOS 14.0+
Desktop (JVM) 11+
Web (JS)
Jetpack Compose / Compose Multiplatform 1.9.3+
Kotlin 2.2.0+

Supported Platforms

Web(JS) uses imperative DOM overlay instead of Compose HTML DOM nodes to avoid runtime Applier conflicts in Compose UI(Canvas) apps.

Desktop (macOS) Troubleshooting

If you see IllegalAccessError with sun.awt, sun.lwawt, or sun.lwawt.macosx while running JCEF on macOS, add JVM module options:

compose.desktop {
    application {
        jvmArgs += listOf(
            "--add-exports=java.desktop/sun.awt=ALL-UNNAMED",
            "--add-opens=java.desktop/sun.awt=ALL-UNNAMED",
            "--add-exports=java.desktop/sun.lwawt=ALL-UNNAMED",
            "--add-opens=java.desktop/sun.lwawt=ALL-UNNAMED",
            "--add-exports=java.desktop/sun.lwawt.macosx=ALL-UNNAMED",
            "--add-opens=java.desktop/sun.lwawt.macosx=ALL-UNNAMED",
        )
    }
}

API Support Matrix

🎯 Project Focus & Comparison

This library has a slightly different focus compared to other WebView libraries (like KevinnZou/compose-webview-multiplatform), primarily targeting Mobile productivity.

1. Mobile-First & Advanced JSBridge

We focused heavily on making the interaction between Kotlin and JavaScript as seamless as possible on Android & iOS.

Promise-based JSBridge: Enables using await in JavaScript to call Native functions and get results directly, avoiding callback hell.
Flexible Serialization: Supports Kotlinx Serialization out-of-the-box, while the BridgeSerializer interface allows plugging in Gson, Moshi, or any other JSON library.
Type Safety: Allows passing complex data objects with full type safety.

2. Platform Support Status

Mobile (Android/iOS): Stable and Feature-Rich. Recommended for production.
Desktop & Web: Currently Experimental (WIP).

📦 Installation

This library is available on Maven Central for universal access without authentication.

Current coordinates: io.github.parkwoocheol:compose-webview:<version>

Step 1. Configure Repository

Add Maven Central to settings.gradle.kts (or settings.gradle):

Kotlin DSL (settings.gradle.kts):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Groovy DSL (settings.gradle):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Step 2. Add Dependency

Add the dependency to your commonMain source set (for KMP) or app dependencies.

Kotlin DSL (build.gradle.kts):

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.parkwoocheol:compose-webview:<version>")
        }
    }
}

Groovy DSL (build.gradle):

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'io.github.parkwoocheol:compose-webview:<version>'
            }
        }
    }
}

Platform-Specific Artifacts

When you add the dependency:

implementation("io.github.parkwoocheol:compose-webview:<version>")

The Kotlin Multiplatform Gradle plugin automatically selects the correct platform-specific artifact for each target:

Note: You don't need to specify platform-specific artifacts manually. Just use compose-webview and Gradle resolves the correct artifact automatically.

Quick Start

@Composable
fun MyWebViewScreen() {
    ComposeWebView(
        url = "https://example.com",
        modifier = Modifier.fillMaxSize(),
        onCreated = { webView ->
            webView.settings.javaScriptEnabled = true
        }
    )
}

State Management

The library provides two ways to create and remember the WebViewState:

1. Persistent State (Recommended)

Uses rememberSaveable to preserve the latest top-level WebView request across configuration changes (e.g., screen rotation). On Android, native WebView state is also restored when available. Other platforms restore the latest top-level loadUrl() or loadHtml() request rather than the full browser session.

val state = rememberSaveableWebViewState(url = "https://google.com")
// or for HTML data
val state = rememberSaveableWebViewStateWithData(data = htmlContent)

WebViewController.loadUrl() and loadHtml() participate in this restoration flow. postUrl() still runs on Android/iOS, but it is intentionally not auto-replayed after recreation because resubmitting POST requests can cause side effects.

2. Transient State (Lightweight)

Uses remember to hold the state. The WebView will be reloaded and state lost on configuration changes. Use this if you want to avoid TransactionTooLargeException with large HTML data or don't need state persistence.

val state = rememberWebViewState(url = "https://google.com")
// or for HTML data
val state = rememberWebViewStateWithData(data = htmlContent)

Usage

Basic Usage

Create a simple WebView with minimal configuration:

@Composable
fun SimpleWebView() {
    ComposeWebView(
        url = "https://google.com",
        modifier = Modifier.fillMaxSize(),
        onCreated = { webView ->
            webView.settings.apply {
                javaScriptEnabled = true
                domStorageEnabled = true
                loadWithOverviewMode = true
                useWideViewPort = true
            }
        }
    )
}

WebView State and Controller

Monitor and control WebView state using WebViewController:

JSBridge - Kotlin to JavaScript Communication

Communicate between Kotlin and JavaScript using type-safe, promise-based API.

Define Data Models

@Serializable
data class User(val name: String, val age: Int)

@Serializable
data class ( success: ,  message: String)


  ( latitude: ,  longitude: )

Register Handlers in Kotlin

Call from JavaScript

register<T, R> null input rules:

T is Unit: call("method") and call("method", null) are both accepted.
Other non-null input types: null throws an input type error.

Use registerNullable<T, R> when a payload type may be null from JavaScript.

registerWithContext<T, R> exposes sourceOrigin, isMainFrame, and transport. On Android these values are most useful with rememberAndroidWebViewJsBridge(...), which uses origin-aware WebView message APIs for documents matched by allowedOriginRules.

Choosing a Bridge

Android Origin-Aware Bridge

For Android web content served from origins listed in allowedOriginRules, prefer rememberAndroidWebViewJsBridge(...) from your Android source set over the default bridge:

val bridge =
    rememberAndroidWebViewJsBridge(
        config =
            AndroidWebViewJsBridgeConfig(
                allowedOriginRules = setOf("https://example.com"),
                policy = AndroidJsBridgePolicy.OriginAwareOnly,
            ),
    )

Notes:

Android Experimental Message APIs

The origin-aware Android bridge also exposes optional experimental APIs for raw string/binary messages and main-frame message-channel sessions:

@OptIn(ExperimentalComposeWebViewApi::class)
LaunchedEffect(bridge) {
    bridge.registerMessage("echoText") { message ->
        when (message) {
            is AndroidBridgeMessage.Text -> AndroidBridgeMessage.Text("echo:${message.value}")
            is AndroidBridgeMessage.Binary -> AndroidBridgeMessage.Binary(message.value)
        }
    }

    bridge.postMainFrameMessage(
        targetOrigin = "https://example.com",
        message = AndroidBridgeMessage.Text("native-ready"),
    )

    val session = bridge.openMainFrameSession()
    session?.setMessageHandler { payload ->
        println()
    }
}

These experimental APIs map directly to Android postWebMessage and WebMessageChannel. Treat them as main-frame transport primitives, not as the same trust boundary as inbound addWebMessageListener. Use an exact targetOrigin such as https://example.com; wildcard target origins are rejected.

JavaScript helpers added by the origin-aware Android bridge:

Customizing Bridge Name

Change the global JavaScript object name:

val bridge = rememberWebViewJsBridge(
    jsObjectName = "MyBridge" // Access via window.MyBridge in JavaScript
)

Lifecycle Management

ComposeWebView automatically handles lifecycle events:

@Composable
fun WebViewWithLifecycle() {
    val state = rememberSaveableWebViewState(url = "https://example.com")

    // Lifecycle events are handled automatically:
    // - onResume() when composable enters composition
    // - onPause() when composable leaves composition
    // - Cleanup when disposed

    ComposeWebView(
        state = state,
        modifier = Modifier.fillMaxSize()
    )
}

Error Handling

Handle WebView errors and display custom error UI:

Custom WebView Configuration

Configure WebView behavior using WebViewSettings:


 {
     state = rememberSaveableWebViewState(url = )

     settings = WebViewSettings(
        userAgent = ,
        javaScriptEnabled = ,
        domStorageEnabled = ,
        cacheMode = CacheMode.CACHE_ELSE_NETWORK,
        supportZoom = ,
        loadWithOverviewMode = ,
        useWideViewPort = ,
        mediaPlaybackRequiresUserAction = ,
        allowFileAccess = ,
        allowContentAccess = ,
        allowFileAccessFromFileURLs = ,
        allowUniversalAccessFromFileURLs = 
    )

    ComposeWebView(
        state = state,
        settings = settings,
        modifier = Modifier.fillMaxSize(),
        onCreated = { webView ->
            
        },
        onDispose = { webView ->
            
        }
    )
}

Scroll Position Tracking

Track and respond to scroll position changes:

Console Message Debugging

Capture JavaScript console messages for debugging:

Configuring WebView Clients

Configure WebView client events using rememberWebViewClient and rememberWebChromeClient:

Basic Usage

Chaining Multiple Handlers

You can also chain handlers:

@Composable
fun ChainedHandlersExample() {
    val client = rememberWebViewClient()
        .onPageStarted { view, url, favicon -> /* ... */ }
        .onPageFinished { view, url -> /* ... */ }
        .onReceivedError { view, request, error -> /* ... */ }

    val chromeClient = rememberWebChromeClient()
        .onProgressChanged { view, progress -> /* ... */ }
        .onConsoleMessage { view, message -> false }

    ComposeWebView(
        state = rememberSaveableWebViewState(url = ),
        client = client,
        chromeClient = chromeClient,
        modifier = Modifier.fillMaxSize()
    )
}

Advanced Customization

For more advanced scenarios, you can still extend the client classes directly:

@Composable
fun AdvancedClientExample() {
    val client = remember {
        object : ComposeWebViewClient() {
            override fun onPageFinished(view: ?, url: ?) {
                .onPageFinished(view, url)
                
                view?.evaluateJavascript()
            }
        }
    }

    ComposeWebView(
        state = rememberSaveableWebViewState(url = ),
        client = client,
        modifier = Modifier.fillMaxSize()
    )
}

Available Client Handlers

WebViewClient:

onPageStarted(handler: (WebView?, String?, PlatformBitmap?) -> Unit)
onPageFinished(handler: (WebView?, String?) -> Unit)
onReceivedError(handler: (WebView?, PlatformWebResourceRequest?, PlatformWebResourceError?) -> Unit)
shouldInterceptRequest(handler: (WebView?, PlatformWebResourceRequest?) -> PlatformWebResourceResponse?)
shouldOverrideUrlLoading(handler: (WebView?, PlatformWebResourceRequest?) -> Boolean)

WebChromeClient:

onProgressChanged(handler: (WebView?, Int) -> Unit)
onConsoleMessage(handler: (WebView?, ConsoleMessage) -> Boolean)
onPermissionRequest(handler: (PlatformPermissionRequest) -> Unit) (Platform-specific)

API Reference

ComposeWebView

Main composable function for displaying WebView.

WebViewState

Holds the state of the WebView.

class WebViewState(
    webContent: WebContent
) {
    var lastLoadedUrl: String?
    var content: WebContent
    val loadingState: LoadingState
    val isLoading: Boolean
    var pageTitle: String?
    var pageIcon: PlatformBitmap?
    var scrollPosition: ScrollPosition
    val errorsForCurrentRequest: SnapshotStateList<WebViewError>
    var jsDialogState: JsDialogState?
     customViewState: CustomViewState?
     webView: WebView?
     bundle: PlatformBundle?
}

WebViewController

Controls WebView navigation and operations.

WebViewJsBridge

Manages JavaScript-Kotlin communication.

ComposeWebViewClient

Handles navigation and page lifecycle events. Can be configured using extension functions.

Extension Functions for Configuration:

ComposeWebChromeClient

Handles UI events like progress updates and console messages. Can be configured using extension functions.

expect open class ComposeWebChromeClient() {
    open fun onProgressChanged(view: WebView?, newProgress: Int)
    open fun onConsoleMessage(view: WebView?, message: ConsoleMessage): 
}

Extension Functions for Configuration:

// Configure callbacks using chainable extension functions
fun ComposeWebChromeClient.onProgressChanged(
    handler: (WebView?, Int) -> Unit
): ComposeWebChromeClient

fun ComposeWebChromeClient.: ComposeWebChromeClient

: ComposeWebChromeClient

Remember Functions

Custom Serializer

Implement BridgeSerializer to use custom JSON libraries like Gson or Moshi:

Sample Apps

The sample/ directory contains runnable targets for every platform:

sample/shared: the Compose Multiplatform UI/features showcased below.
sample/androidApp: Android wrapper (Gradle module).
sample/iosApp: Xcode project that embeds the shared UI.
sample/desktopApp: Compose Desktop entry point.
sample/wasmApp: Compose WASM/browser runner.

Features Demonstrated

All sample targets use the same feature screens:

Running the Samples

Contributing

We welcome contributions from the community! Whether it's reporting bugs, suggesting features, improving docs, or submitting code.

Contributing Quick Start

Fork the repository
Create your branch (git checkout -b your-branch-name)
Make your changes
Test with the sample app
Push and open a Pull Request

See CONTRIBUTING.md for more details.

Release History

Release history is maintained in CHANGELOG.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

ComposeNativeWebview★ 155

kdroidFilterCross-platform WebView component exposing WebViewState and navigator APIs; backed by native OS webviews via Rust+UniFFI (Wry), with JS-native bridge, cookie API, request interceptor.Shared: webview, compose-multiplatform, compose

compose-rich-editor★ 1.8k

MohamedRejebRich text editor library for creating customizable WYSIWYG editors, supporting text styling, links, code blocks, lists, and HTML/Markdown import/export with minimal boilerplate.Shared: compose-multiplatform, compose

compose-hot-reload★ 1.4k

JetBrainsEnhances UI development speed by enabling real-time updates without restarts. Uses a specialized JVM for intelligent code reloading, optimizing the iterative design process.Shared: compose-multiplatform, compose

charty★ 1.3k

hi-manshuLightweight charting toolkit delivering sleek, customizable charts with a minimal API, performant rendering, easy theming, and concise documentation for rapid UI integration.Shared: compose-multiplatform, compose

compose-shimmer★ 1.0k

valentinilkOffers shimmering animation for UI elements, integrated via a simple modifier. Includes customization options like theming and animation boundaries. Supports advanced usage scenarios and custom modifiers.Shared: compose-multiplatform, compose

compottie★ 648

alexzhirkevichCompose Multiplatform port of Lottie, enabling use of animations across various platforms with seamless integration, mirroring usage patterns detailed in the original Lottie documentation.Shared: compose-multiplatform, compose

Android	`AndroidView` (WebView)	✅ Stable	Full feature support
iOS	`UIKitView` (WKWebView)	✅ Stable	Full feature support (Seamless JS Bridge)
Desktop	`SwingPanel` (CEF via JCEF)	🚧 Experimental	WIP: JCEF integration is in progress. Basic browsing works, but advanced features are still being tested.
Web (JS)	`Iframe` (DOM overlay)	🚧 Experimental	WIP: Uses DOM overlay to stay compatible with Compose UI (Canvas). CORS/browser policy limitations apply.
Web (WASM)	`Iframe` (DOM)	🚧 Experimental	WIP: Uses iframe with dynamic positioning. Same-origin policy restrictions apply.

API	Android	iOS	Desktop	Web	Notes
`loadUrl()`	✅	✅	✅	✅	Headers: Android/iOS only
`loadHtml()`	✅	✅	✅	⚠️	Web: CORS restrictions
`postUrl()`	✅	✅	❌	❌	Desktop/Web not supported
`evaluateJavascript()`	✅	✅	✅	⚠️	Web: CORS restricted
`navigateBack/Forward`	✅	✅	✅	⚠️	Web: CORS restricted
`reload() / stopLoading()`	✅	✅	✅	⚠️	Web: CORS restricted

API	Android	iOS	Desktop	Web	Notes
`zoomIn/Out/By()`	✅	❌	✅	❌	iOS: Pinch-to-zoom only
`scrollTo/By()`	✅	✅	❌	✅	Desktop not supported
`pageUp/Down()`	✅	⚠️	❌	⚠️	Via scrollBy on iOS/Web
`findAllAsync()`	✅	❌	❌	❌	iOS/Web/Desktop not supported
`clearCache/History()`	✅	❌	❌	❌	Android only

Feature	Android	iOS	Desktop	Web	Notes
`LoadingState`	✅	✅	⚠️	⚠️	All states supported on Android/iOS
`LoadingState.Loading(progress)`	✅	✅	❌	❌	iOS: 100ms polling
`ScrollPosition`	✅	✅	❌	⚠️	Real-time (Android), Polling (iOS), CORS (Web)
`WebViewError`	✅	✅	⚠️	⚠️	Typed error categories
`jsDialogState`	✅	✅	❌	❌	Alert/Confirm/Prompt
`customViewState`	✅	⚠️	❌	❌	Android: custom view view hierarchy, iOS: native fullscreen signal

Setting	Android	iOS	Desktop	Web	Notes
`interceptedSchemes`	✅	✅	❌	❌	URL schemes to intercept (iOS registration required)
`darkMode`	✅	✅	❌	❌	DARK, LIGHT, or AUTO theme support
`userAgent`	✅	✅	✅	❌	Custom user agent string
`javaScriptEnabled`	✅	✅*	✅	❌	*iOS: Always enabled
`domStorageEnabled`	✅	✅	⚠️	❌	Limited on Desktop
`cacheMode`	✅	⚠️	⚠️	❌	Full support on Android
`supportZoom`	✅	⚠️**	✅	❌	**iOS: Pinch-to-zoom only
`mediaPlaybackRequiresUserAction`	✅	✅	⚠️	❌	Autoplay control

Callback	Android	iOS	Desktop	Web	Notes
`onPageStarted`	✅	✅	✅	❌	Navigation started
`onPageFinished`	✅	✅	✅	✅	Navigation completed
`onProgressChanged`	✅	✅	❌	❌	iOS: 100ms polling
`onReceivedError`	✅	✅	⚠️	❌	Typed error information
`shouldInterceptRequest`	✅	✅	❌	❌	Handle custom request interception
`onConsoleMessage`	✅	✅	❌	❌	JavaScript console debugging
`shouldOverrideUrlLoading`	✅	✅	✅	❌	Custom URL handling
JS Dialogs (Alert/Confirm/Prompt)	✅	✅	❌	❌	Custom dialog UI
Custom View (Fullscreen)	✅	⚠️	❌	❌	Android: custom view injection, iOS: native fullscreen events
File Upload	✅	✅	❌	❌	Native file picker
Download Handling	✅	⚠️	❌	❌	`onDownloadStart` callback

Feature	Android	iOS	Desktop	Web	Notes
`register()` handler	✅	✅	✅	✅	Kotlin ↔ JavaScript calls
`emit()` events	✅	✅	⚠️	⚠️	Event bus system
Promise-based response	✅	✅	⚠️	⚠️	Async/await support
Type-safe serialization	✅	✅	✅	✅	Kotlinx Serialization

Android	`compose-webview-android`	`io.github.parkwoocheol:compose-webview-android:<version>`
iOS (arm64)	`compose-webview-iosarm64`	`io.github.parkwoocheol:compose-webview-iosarm64:<version>`
iOS (x64)	`compose-webview-iosx64`	`io.github.parkwoocheol:compose-webview-iosx64:<version>`
iOS (Simulator arm64)	`compose-webview-iossimulatorarm64`	`io.github.parkwoocheol:compose-webview-iossimulatorarm64:<version>`
Desktop (JVM)	`compose-webview-desktop`	`io.github.parkwoocheol:compose-webview-desktop:<version>`
Web (JS)	`compose-webview-js`	`io.github.parkwoocheol:compose-webview-js:<version>`
Web (WASM)	`compose-webview-wasmjs`	`io.github.parkwoocheol:compose-webview-wasmjs:<version>`
Metadata	`compose-webview`	`io.github.parkwoocheol:compose-webview:<version>`

Cross-platform typed calls and events	`rememberWebViewJsBridge()`	Default for shared code. On Android it keeps the compatibility bridge path.
Android typed calls with origin and frame metadata	`rememberAndroidWebViewJsBridge(..., policy = OriginAwareOnly)`	Android-only. Uses `addWebMessageListener` with `allowedOriginRules`.
Native-to-JavaScript main-frame messages on Android	`postMainFrameMessage(...)`	Android-only experimental API. Maps to `postWebMessage`.
Long-lived bidirectional main-frame channel on Android	`openMainFrameSession(...)`	Android-only experimental API. Maps to `WebMessageChannel` plus `postWebMessage`.
Provider or page fallback that cannot use the origin-aware path	`policy = Compatible`	Re-enables the classic Android bridge fallback. Use only when you accept the weaker trust model.

compose-webview

ComposeWebView

Table of Contents

Documentation

Features

Requirements

Supported Platforms

Desktop (macOS) Troubleshooting

API Support Matrix

🎯 Project Focus & Comparison

1. Mobile-First & Advanced JSBridge

2. Platform Support Status

📦 Installation

Step 1. Configure Repository

Step 2. Add Dependency

Platform-Specific Artifacts

Quick Start

State Management

1. Persistent State (Recommended)

2. Transient State (Lightweight)

Usage

Basic Usage

WebView State and Controller

JSBridge - Kotlin to JavaScript Communication

Define Data Models

Register Handlers in Kotlin

Call from JavaScript

Choosing a Bridge

Android Origin-Aware Bridge

Android Experimental Message APIs

Customizing Bridge Name

Lifecycle Management

Error Handling

Custom WebView Configuration

Scroll Position Tracking

Console Message Debugging

Configuring WebView Clients

Basic Usage

Chaining Multiple Handlers

Advanced Customization

Available Client Handlers

API Reference

ComposeWebView

WebViewState

WebViewController

WebViewJsBridge

ComposeWebViewClient

ComposeWebChromeClient

Remember Functions

Custom Serializer

Sample Apps

Features Demonstrated

Running the Samples

Contributing

Contributing Quick Start

Release History

License

Related libraries

ComposeWebView

Table of Contents

Documentation

Features

Requirements

Supported Platforms

Desktop (macOS) Troubleshooting

API Support Matrix

🎯 Project Focus & Comparison

1. Mobile-First & Advanced JSBridge

2. Platform Support Status

📦 Installation

Step 1. Configure Repository

Step 2. Add Dependency

Platform-Specific Artifacts

Quick Start

State Management

1. Persistent State (Recommended)

2. Transient State (Lightweight)

Usage

Basic Usage

WebView State and Controller