Background
WebView is a component we often use in development. We can use it to display dynamic Html pages. In Android’s View system, we can directly add the WebView component to xml and use it. But in Jetpack Compose, there is no WebView component that can be used directly. So how do we use WebView in Compose?
Native use
The simplest way is to use AndroidView directly to wrap the native WebView:
@Composable
fun MyContent(){
// Declare a string that contains a url
val mUrl = "https://www.google.com"
// Adding a WebView inside AndroidView
// with layout as full screen
AndroidView(factory = {
WebView(it).apply {
layoutParams = ViewGroup.LayoutParams(
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
webViewClient = WebViewClient()
loadUrl(mUrl)
}
}, update = {
it.loadUrl(mUrl)
})
}
As you can see, we created a new WebView directly in the AndroidView factory and specified layoutParams and webViewClient, and then called loadUrl(mUrl) to load the web page.
But this only applies to stateless single loading. What if we need to get the title, loading status, and current loading Url of the web page? Similarly, what if we need to control the forward, backward, and loading of new links on the web page? What’s more complicated is what if we need to support the loading of Post and Html codes at the same time based on loading Url?
This brings us to the protagonist of this article, Accompanist WebView.
Accompanist
https://github.com/google/accompanist
I believe most Compose developers should have come into contact with this library. Its original intention is to extend some practical capabilities to Jetpack Compose. So far, it has provided many practical components such as FlowLayout, Pager, SwipeRefresh, etc. And it also provides an encapsulation of the WebView component, which can help us easily complete the requirements mentioned above.
Note: According to this official announcement, Accompanist will mark WebView as deprecated starting from version 0.33.1-alpha, that is, it will no longer provide maintenance and updates. And it will remove the relevant APIs from the warehouse after two versions. However, we ourselves still rely on and use this library in our projects. Therefore, I forked this library and made some functional improvements, and will continue to update new capabilities in the future. The library has been released to Jitpack, project address: https://github.com/KevinnZou/compose-webview
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation "com.github.KevinnZou:compose-webview:0.33.2"
}
Basic usage
Its basic usage is very simple:
val state = rememberWebViewState("https://example.com")
WebView(
state
)
Two key APIs are mainly used, WebView is used to provide UI layout, and rememberWebViewState is used to provide state.
WebViewState
This is the state class of the WebView component, which maintains the state properties of the WebView internally. For example, the currently loaded Url, currently loaded content, loading status, page title and icon, error status, etc.
/**
* A state holder to hold the state for the WebView. In most cases this will be remembered
* using the rememberWebViewState(uri) function.
*/
@Stable
public class WebViewState(webContent: WebContent) {
public var lastLoadedUrl: String? by mutableStateOf(null)
internal set
/**
* The content being loaded by the WebView
*/
public var content: WebContent by mutableStateOf(webContent)
/**
* Whether the WebView is currently [LoadingState.Loading] data in its main frame (along with
* progress) or the data loading has [LoadingState.Finished]. See [LoadingState]
*/
public var loadingState: LoadingState by mutableStateOf(LoadingState.Initializing)
internal set
/**
* Whether the webview is currently loading data in its main frame
*/
public val isLoading: Boolean
get() = loadingState !is Finished
/**
* The title received from the loaded content of the current page
*/
public var pageTitle: String? by mutableStateOf(null)
internal set
/**
* the favicon received from the loaded content of the current page
*/
public var pageIcon: Bitmap? by mutableStateOf(null)
internal set
/**
* A list for errors captured in the last load. Reset when a new page is loaded.
* Errors could be from any resource (iframe, image, etc.), not just for the main page.
* For more fine grained control use the OnError callback of the WebView.
*/
public val errorsForCurrentRequest: SnapshotStateList<WebViewError> = mutableStateListOf()
/**
* The saved view state from when the view was destroyed last. To restore state,
* use the navigator and only call loadUrl if the bundle is null.
* See WebViewSaveStateSample.
*/
public var viewState: Bundle? = null
internal set
// We need access to this in the state saver. An internal DisposableEffect or AndroidView
// onDestroy is called after the state saver and so can't be used.
internal var webView by mutableStateOf<WebView?>(null)
}
RememberWebViewState provides a basic WebViewState for loading Url.
/**
* Creates a WebView state that is remembered across Compositions.
*
* @param url The url to load in the WebView
* @param additionalHttpHeaders Optional, additional HTTP headers that are passed to [WebView.loadUrl].
* Note that these headers are used for all subsequent requests of the WebView.
*/
@Composable
public fun rememberWebViewState(
url: String,
additionalHttpHeaders: Map<String, String> = emptyMap()
): WebViewState =
// Rather than using .apply {} here we will recreate the state, this prevents
// a recomposition loop when the webview updates the url itself.
remember {
WebViewState(
WebContent.Url(
url = url,
additionalHttpHeaders = additionalHttpHeaders
)
)
}.apply {
this.content = WebContent.Url(
url = url,
additionalHttpHeaders = additionalHttpHeaders
)
}
With WebViewState, we can obtain Web-related properties externally and display them:
Column {
val state = rememberWebViewState("https://example.com")
Text(text = "${state.pageTitle}")
val loadingState = state.loadingState
if (loadingState is LoadingState.Loading) {
LinearProgressIndicator(
progress = loadingState.progress,
modifier = Modifier.fillMaxWidth()
)
}
WebView(
state
)
}
WebViewNavigator
Another important class is WebViewNavigator, which encapsulates WebView navigation-related capabilities and exposes them to developers. For example, forward, backward, reload, stop loading, etc. In addition, basic loading capabilities such as loading links, Post data, and loading Html are also encapsulated here, and will eventually be passed to WebView to complete the loading of links.
/**
* Allows control over the navigation of a WebView from outside the composable. E.g. for performing
* a back navigation in response to the user clicking the "up" button in a TopAppBar.
*
* @see [rememberWebViewNavigator]
*/
@Stable
public class WebViewNavigator(private val coroutineScope: CoroutineScope) {
private sealed interface NavigationEvent {
data object Back : NavigationEvent
data object Forward: NavigationEvent
data object Reload : NavigationEvent
data object StopLoading : NavigationEvent
data class LoadUrl(
val url: String,
val additionalHttpHeaders: Map<String, String> = emptyMap()
) : NavigationEvent
data class LoadHtml(
val html: String,
val baseUrl: String? = null,
val mimeType: String? = null,
val encoding: String? = "utf-8",
val historyUrl: String? = null
) : NavigationEvent
data class PostUrl(
val url: String,
val postData: ByteArray
) : NavigationEvent
}
private val navigationEvents: MutableSharedFlow<NavigationEvent> = MutableSharedFlow(replay = 1)
// Use Dispatchers.Main to ensure that the webview methods are called on UI thread
internal suspend fun WebView.handleNavigationEvents(): Nothing = withContext(Dispatchers.Main) {
navigationEvents.collect { event ->
when (event) {
is NavigationEvent.Back -> goBack()
is NavigationEvent.Forward -> goForward()
is NavigationEvent.Reload -> reload()
is NavigationEvent.StopLoading -> stopLoading()
is NavigationEvent.LoadHtml -> loadDataWithBaseURL(
event.baseUrl,
event.html,
event.mimeType,
event.encoding,
event.historyUrl
)
is NavigationEvent.LoadUrl -> {
loadUrl(event.url, event.additionalHttpHeaders)
}
is NavigationEvent.PostUrl -> {
postUrl(event.url, event.postData)
}
}
}
}
/**
* True when the web view is able to navigate backwards, false otherwise.
*/
public var canGoBack: Boolean by mutableStateOf(false)
internal set
/**
* True when the web view is able to navigate forwards, false otherwise.
*/
public var canGoForward: Boolean by mutableStateOf(false)
internal set
public fun loadUrl(url: String, additionalHttpHeaders: Map<String, String> = emptyMap()) {
coroutineScope.launch {
navigationEvents.emit(
NavigationEvent.LoadUrl(
url,
additionalHttpHeaders
)
)
}
}
public fun loadHtml(
html: String,
baseUrl: String? = null,
mimeType: String? = null,
encoding: String? = "utf-8",
historyUrl: String? = null
) {
coroutineScope.launch {
navigationEvents.emit(
NavigationEvent.LoadHtml(
html,
baseUrl,
mimeType,
encoding,
historyUrl
)
)
}
}
public fun postUrl(
url: String,
postData: ByteArray
) {
coroutineScope.launch {
navigationEvents.emit(
NavigationEvent.PostUrl(
url,
postData
)
)
}
}
/**
* Navigates the webview back to the previous page.
*/
public fun navigateBack() {
coroutineScope.launch { navigationEvents.emit(NavigationEvent.Back) }
}
/**
* Navigates the webview forward after going back from a page.
*/
public fun navigateForward() {
coroutineScope.launch { navigationEvents.emit(NavigationEvent.Forward) }
}
/**
* Reloads the current page in the webview.
*/
public fun reload() {
coroutineScope.launch { navigationEvents.emit(NavigationEvent.Reload) }
}
/**
* Stops the current page load (if one is loading).
*/
public fun stopLoading() {
coroutineScope.launch { navigationEvents.emit(NavigationEvent.StopLoading) }
}
}
rememberWebViewNavigator provides a default navigator and saves it in remember.
/**
* Creates and remembers a [WebViewNavigator] using the default [CoroutineScope] or a provided
*override.
*/
@Composable
public fun rememberWebViewNavigator(
coroutineScope: CoroutineScope = rememberCoroutineScope()
): WebViewNavigator = remember(coroutineScope) { WebViewNavigator(coroutineScope) }
In use, we can control the forward and backward movement of WebView through navigator.
Column {
val state = rememberWebViewState("https://example.com")
val navigator = rememberWebViewNavigator()
TopAppBar(
title = { Text(text = "WebView Sample") },
navigationIcon = {
if (navigator.canGoBack) {
IconButton(onClick = { navigator.navigateBack() }) {
icon(
imageVector = Icons.Default.ArrowBack,
contentDescription = "Back"
)
}
}
}
)
Text(text = "${state.pageTitle}")
val loadingState = state.loadingState
if (loadingState is LoadingState.Loading) {
LinearProgressIndicator(
progress = loadingState.progress,
modifier = Modifier.fillMaxWidth()
)
}
WebView(
state = state,
navigator = navigator
)
}
WebView
Finally let’s take a look at its complete API:
/**
* A wrapper around the Android View WebView to provide a basic WebView composable.
*
* If you require more customization you are most likely better rolling your own and using this
* wrapper as an example.
*
* The WebView attempts to set the layoutParams based on the Compose modifier passed in. If it
* is incorrectly sizing, use the layoutParams composable function instead.
*
* @param state The webview state holder where the Uri to load is defined.
* @param modifier A compose modifier
* @param captureBackPresses Set to true to have this Composable capture back presses and navigate
* the WebView back.
* @param navigator An optional navigator object that can be used to control the WebView's
* navigation from outside the composable.
* @param onCreated Called when the WebView is first created, this can be used to set additional
* settings on the WebView. WebChromeClient and WebViewClient should not be set here as they will be
* subsequently overwritten after this lambda is called.
* @param onDispose Called when the WebView is destroyed. Provides a bundle which can be saved
* if you need to save and restore state in this WebView.
* @param client Provides access to WebViewClient via subclassing
* @param chromeClient Provides access to WebChromeClient via subclassing
* @param factory An optional WebView factory for using a custom subclass of WebView
*/
@Composable
public fun WebView(
state: WebViewState,
modifier: Modifier = Modifier,
captureBackPresses: Boolean = true,
navigator: WebViewNavigator = rememberWebViewNavigator(),
onCreated: (WebView) -> Unit = {},
onDispose: (WebView) -> Unit = {},
client: AccompanistWebViewClient = remember { AccompanistWebViewClient() },
chromeClient: AccompanistWebChromeClient = remember { AccompanistWebChromeClient() },
factory: ((Context) -> WebView)? = null,
)
As you can see, several important parameters have been introduced before, and the rest are easy to understand. Note the last parameter, which allows developers to provide a factory method to create a custom WebView. If there is already a customized WebView in the project, it can be passed in through this method.
WebView(
...
factory = { context -> CustomWebView(context) }
)
Complete example
class BasicWebViewSample : ComponentActivity() {
val initialUrl = "https://google.com"
@SuppressLint("SetJavaScriptEnabled")
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
AccompanistSampleTheme {
val state = rememberWebViewState(url = initialUrl)
val navigator = rememberWebViewNavigator()
var textFieldValue by remember(state.lastLoadedUrl) {
mutableStateOf(state.lastLoadedUrl)
}
Column {
TopAppBar(
title = { Text(text = "WebView Sample") },
navigationIcon = {
if (navigator.canGoBack) {
IconButton(onClick = { navigator.navigateBack() }) {
icon(
imageVector = Icons.Default.ArrowBack,
contentDescription = "Back"
)
}
}
}
)
Row {
Box(modifier = Modifier.weight(1f)) {
if (state.errorsForCurrentRequest.isNotEmpty()) {
Image(
imageVector = Icons.Default.Error,
contentDescription = "Error",
colorFilter = ColorFilter.tint(Color.Red),
modifier = Modifier
.align(Alignment.CenterEnd)
.padding(8.dp)
)
}
OutlinedTextField(
value = textFieldValue ?: "",
onValueChange = { textFieldValue = it },
modifier = Modifier.fillMaxWidth()
)
}
Button(
onClick = {
textFieldValue?.let {
navigator.loadUrl(it)
}
},
modifier = Modifier.align(Alignment.CenterVertically)
) {
Text("Go")
}
}
val loadingState = state.loadingState
if (loadingState is LoadingState.Loading) {
LinearProgressIndicator(
progress = loadingState.progress,
modifier = Modifier.fillMaxWidth()
)
}
// A custom WebViewClient and WebChromeClient can be provided via subclassing
val webClient = remember {
object : AccompanistWebViewClient() {
override fun onPageStarted(
view: WebView,
url: String?,
favicon: Bitmap?
) {
super.onPageStarted(view, url, favicon)
Log.d("Accompanist WebView", "Page started loading for $url")
}
}
}
WebView(
state = state,
modifier = Modifier
.weight(1f),
navigator = navigator,
onCreated = { webView ->
webView.settings.javaScriptEnabled = true
},
client=webClient
)
}
}
}
}
}
Download
repositories {
mavenCentral()
}
dependencies {
implementation "com.google.accompanist:accompanist-webview:0.33.1-alpha"
}
Note: The accompanist webview library has stopped maintenance. It is recommended to use the version I forked:
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation "com.github.KevinnZou:compose-webview:0.33.2"
}
Summary
Compared with the simple method of using WebView wrapped in AndroidView, the Accompanist library provides a WebView with more complete functions, higher degree of customization, and easier use. But unfortunately it has stopped maintenance. Everyone is welcome to use my forked version and make suggestions for improvements!