NavHostController

open class NavHostController : NavController

Known direct subclasses
TestNavHostController

Subclass of NavHostController that offers additional APIs for testing Navigation.


Subclass of NavController that offers additional APIs for use by a NavHost to connect the NavController to external dependencies.

Apps should generally not construct controllers, instead obtain a relevant controller directly from a navigation host via NavHost.getNavController or by using one of the utility methods on the Navigation class.

Summary

Public constructors

Public functions

final Unit

Set whether the NavController should handle the system Back button events via the registered OnBackPressedDispatcher.

final Unit

Sets the host's LifecycleOwner.

final Unit

Sets the host's OnBackPressedDispatcher.

final Unit

Sets the host's ViewModelStore used by the NavController to store ViewModels at the navigation graph level.

Inherited functions

From androidx.navigation.NavController
open Unit

Adds an OnDestinationChangedListener to this controller to receive a callback whenever the currentDestination or its arguments change.

Boolean

Clears any saved state associated with destinationId that was previously saved via popBackStack when using a saveState value of true.

Boolean

Clears any saved state associated with route that was previously saved via popBackStack when using a saveState value of true.

open NavDeepLinkBuilder

Create a deep link to a destination within this NavController.

open NavBackStackEntry
getBackStackEntry(destinationId: @IdRes Int)

Gets the topmost NavBackStackEntry for a destination id.

NavBackStackEntry

Gets the topmost NavBackStackEntry for a route.

open ViewModelStoreOwner

Gets the ViewModelStoreOwner for a NavGraph.

open Boolean

Checks the given Intent for a Navigation deep link and navigates to the deep link if present.

open Unit
@MainThread
navigate(deepLink: Uri)

Navigate to a destination via the given deep link Uri.

open Unit

Navigate via the given NavDirections

open Unit

Navigate to a destination via the given NavDeepLinkRequest.

open Unit

Navigate to a destination from the current navigation graph.

open Unit
@MainThread
navigate(deepLink: Uri, navOptions: NavOptions?)

Navigate to a destination via the given deep link Uri.

open Unit
@MainThread
navigate(directions: NavDirections, navOptions: NavOptions?)

Navigate via the given NavDirections

open Unit
@MainThread
navigate(directions: NavDirections, navigatorExtras: Navigator.Extras)

Navigate via the given NavDirections

open Unit

Navigate to a destination via the given NavDeepLinkRequest.

open Unit
@MainThread
navigate(resId: @IdRes Int, args: Bundle?)

Navigate to a destination from the current navigation graph.

Unit
@MainThread
navigate(route: String, builder: NavOptionsBuilder.() -> Unit)

Navigate to a route in the current NavGraph.

open Unit
@MainThread
navigate(
    deepLink: Uri,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination via the given deep link Uri.

open Unit
@MainThread
navigate(
    request: NavDeepLinkRequest,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination via the given NavDeepLinkRequest.

open Unit
@MainThread
navigate(resId: @IdRes Int, args: Bundle?, navOptions: NavOptions?)

Navigate to a destination from the current navigation graph.

Unit
@MainThread
navigate(
    route: String,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a route in the current NavGraph.

open Unit
@MainThread
navigate(
    resId: @IdRes Int,
    args: Bundle?,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination from the current navigation graph.

open Boolean

Attempts to navigate up in the navigation hierarchy.

open Boolean

Attempts to pop the controller's back stack.

open Boolean
@MainThread
popBackStack(destinationId: @IdRes Int, inclusive: Boolean)

Attempts to pop the controller's back stack back to a specific destination.

open Boolean
@MainThread
popBackStack(
    destinationId: @IdRes Int,
    inclusive: Boolean,
    saveState: Boolean
)

Attempts to pop the controller's back stack back to a specific destination.

Boolean
@MainThread
popBackStack(route: String, inclusive: Boolean, saveState: Boolean)

Attempts to pop the controller's back stack back to a specific destination.

open Unit

Removes an OnDestinationChangedListener from this controller.

open Unit

Restores all navigation controller state from a bundle.

open Bundle?

Saves all navigation controller state to a Bundle.

open Unit

Sets the navigation graph to the specified resource.

open Unit
@MainThread
@CallSuper
setGraph(graph: NavGraph, startDestinationArgs: Bundle?)

Sets the navigation graph to the specified graph.

open Unit
@MainThread
@CallSuper
setGraph(graphResId: @NavigationRes Int, startDestinationArgs: Bundle?)

Sets the navigation graph to the specified resource.

Inherited properties

From androidx.navigation.NavController
open NavBackStackEntry?

The topmost NavBackStackEntry.

Flow<NavBackStackEntry>

A Flow that will emit the currently active NavBackStackEntry whenever it changes.

open NavDestination?

The current destination.

open NavGraph

The topmost navigation graph associated with this NavController.

open NavInflater

The inflater for this controller.

open NavigatorProvider

The NavController's NavigatorProvider.

open NavBackStackEntry?

The previous visible NavBackStackEntry.

StateFlow<List<NavBackStackEntry>>

A StateFlow that will emit the currently visible NavBackStackEntries whenever they change.

Public constructors

Added in 2.1.0
NavHostController(context: Context)

Public functions

enableOnBackPressed

Added in 2.1.0
final fun enableOnBackPressed(enabled: Boolean): Unit

Set whether the NavController should handle the system Back button events via the registered OnBackPressedDispatcher.

Parameters
enabled: Boolean

True if the NavController should handle system Back button events.

setLifecycleOwner

Added in 2.1.0
final fun setLifecycleOwner(owner: LifecycleOwner): Unit

Sets the host's LifecycleOwner.

Parameters
owner: LifecycleOwner

The LifecycleOwner associated with the containing NavHost.

setOnBackPressedDispatcher

Added in 2.1.0
final fun setOnBackPressedDispatcher(dispatcher: OnBackPressedDispatcher): Unit

Sets the host's OnBackPressedDispatcher. If set, NavController will register a onBackPressedCallback to handle system Back button events.

You must explicitly called setLifecycleOwner before calling this method as the owner set there will be used as the LifecycleOwner for registering the onBackPressedCallback.

You can dynamically enable and disable whether the NavController should handle the system Back button events by calling enableOnBackPressed.

Parameters
dispatcher: OnBackPressedDispatcher

The OnBackPressedDispatcher associated with the containing NavHost.

Throws
kotlin.IllegalStateException

if you have not called setLifecycleOwner before calling this method.

setViewModelStore

Added in 2.1.0
final fun setViewModelStore(viewModelStore: ViewModelStore): Unit

Sets the host's ViewModelStore used by the NavController to store ViewModels at the navigation graph level. This is required to call getViewModelStoreOwner and should generally be called for you by your NavHost.

You must call this method before setGraph or similar methods, because the ViewModelStore set here will be used by the created NavBackStackEntry items.

Parameters
viewModelStore: ViewModelStore

ViewModelStore used to store ViewModels at the navigation graph level

Throws
kotlin.IllegalStateException

if this method is called when graph was already set via setGraph or similar methods.