Navigator

From a content page to a controllable browsing flow

Embedded pages rarely need a full browser, but task flows still need a few browser controls: return after submitting a form, cancel a slow request, or open a help article from an in-app menu. controller.navigator is the navigation entry point for the same native WebView owned by the current WebViewController.

See the Navigator Dokka API for complete signatures.

Bind capability state to buttons

canGoBack and canGoForward are observable Compose state synchronized with the native history. Use them directly for button enabled values instead of maintaining a parallel history stack.

@Composable
fun ArticleActions(controller: WebViewController<*>) {
    val navigator = controller.navigator
    Button(enabled = navigator.canGoBack, onClick = { navigator.goBack() }) { Text("Back") }
    Button(enabled = navigator.canGoForward, onClick = { navigator.goForward() }) { Text("Forward") }
}

The return values of goBack() and goForward() describe whether another step remains after the request; normal UI should continue reading the observable state.

Operations at a glance

Operation	Typical use	Result and caveat	Dokka
`goBack()`	Return within the page	Requests the previous history entry; return value indicates whether another back step remains.	`goBack`
`goForward()`	Undo a back action	Requests the next history entry.	`goForward`
`refresh()`	Reload the last successful page	Delegates to the native WebView reload.	`refresh`
`stop()`	Cancel an in-progress load	Stops only when the backend can cancel at that moment.	`stop`
`loadUrl(url)`	Open or retry a URL	Starts a new top-level navigation.	`loadUrl`

Navigate, refresh, and retry

Button(onClick = { controller.navigator.loadUrl("https://example.com/help/account") }) {
    Text("Account help")
}
if (controller.loadingState is LoadingState.Loading) {
    Button(onClick = { controller.navigator.stop() }) { Text("Cancel") }
}

refresh() reloads the most recently successful page. To retry a failed address, call loadUrl(controller.url) when LoadingEnd.success is false.

Lifecycle and platform behavior

rememberWebViewController(initialUrl) triggers the first load after WebView(controller) is composed and the native view reaches Ready:

rememberWebViewController(initialUrl)
              │
              ▼
     WebView(controller) enters composition
              │ native view ready
              ▼
      first loadUrl(initialUrl)
              │
              ▼
  Loading ───────────────> LoadingEnd
              ▲                │
              └─ loadUrl / refresh / history / redirect ─┘

For URL policy before navigation, see Interceptors. For creation-time options, see WebViewConfig.