NavHostController

Kotlin |Java

open class NavHostController : NavController

kotlin.Any
↳	androidx.navigation.NavController
	↳	androidx.navigation.NavHostController

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

Inherited constants

From class NavController

String

KEY_DEEP_LINK_INTENT

The Intent that triggered a deep link to the current destination.

Public constructors
`<init>(@NonNull context: Context)` Construct a new controller for a given `Context` suitable for use in a `NavHost`.

Public methods
Unit	`enableOnBackPressed(enabled: Boolean)` Set whether the NavController should handle the system Back button events via the registered `OnBackPressedDispatcher`.
Unit	`setLifecycleOwner(@NonNull owner: LifecycleOwner)` Sets the host's `LifecycleOwner`.
Unit	`setOnBackPressedDispatcher(@NonNull dispatcher: OnBackPressedDispatcher)` Sets the host's `OnBackPressedDispatcher`.
Unit	`setViewModelStore(@NonNull viewModelStore: ViewModelStore)` Sets the host's ViewModelStore used by the NavController to store ViewModels at the navigation graph level.

Inherited functions

From class NavController

`Unit`	`addOnDestinationChangedListener(@NonNull listener: NavController.OnDestinationChangedListener)` Adds an `OnDestinationChangedListener` to this controller to receive a callback whenever the `getCurrentDestination()` or its arguments change. The current destination, if any, will be immediately sent to your listener.
`NavDeepLinkBuilder`	`createDeepLink()` Create a deep link to a destination within this NavController.
`NavBackStackEntry`	`getBackStackEntry(@IdRes destinationId: Int)` Gets the topmost `NavBackStackEntry` for a destination id. This is always safe to use with `the current destination` or `its parent` or grandparent navigation graphs as these destinations are guaranteed to be on the back stack.
`NavBackStackEntry?`	`getCurrentBackStackEntry()` Gets the topmost `NavBackStackEntry`.
`NavDestination?`	`getCurrentDestination()` Gets the current destination.
`NavGraph`	`getGraph()` Gets the topmost navigation graph associated with this NavController.
`NavInflater`	`getNavInflater()` Returns the `inflater` for this controller.
`NavigatorProvider`	`getNavigatorProvider()` Retrieve the NavController's `NavigatorProvider`. All `Navigators` used to construct the `navigation graph` for this nav controller should be added to this navigator provider before the graph is constructed. Generally, the Navigators are set for you by the `NavHost` hosting this NavController and you do not need to manually interact with the navigator provider.
`NavBackStackEntry?`	`getPreviousBackStackEntry()` Gets the previous visible `NavBackStackEntry`. This skips over any `NavBackStackEntry` that is associated with a `NavGraph`.
`ViewModelStoreOwner`	`getViewModelStoreOwner(@IdRes navGraphId: Int)` Gets the `ViewModelStoreOwner` for a NavGraph. This can be passed to `androidx.lifecycle.ViewModelProvider` to retrieve a ViewModel that is scoped to the navigation graph - it will be cleared when the navigation graph is popped off the back stack.
`Boolean`	`handleDeepLink(@Nullable intent: Intent?)` Checks the given Intent for a Navigation deep link and navigates to the deep link if present. This is called automatically for you the first time you set the graph if you've passed in an `Activity` as the context when constructing this NavController, but should be manually called if your Activity receives new Intents in `Activity#onNewIntent(Intent)`. The types of Intents that are supported include: Intents created by `NavDeepLinkBuilder` or `createDeepLink()`. This assumes that the current graph shares the same hierarchy to get to the deep linked destination as when the deep link was constructed. Intents that include a `data Uri`. This Uri will be checked against the Uri patterns in the `NavDeepLinks` added via `NavDestination#addDeepLink(NavDeepLink)`. The `navigation graph` should be set before calling this method.
`Unit`	`navigate(@IdRes resId: Int)` Navigate to a destination from the current navigation graph. This supports both navigating via an `action` and directly navigating to a destination.
`Unit`	`navigate(@IdRes resId: Int, @Nullable args: Bundle?)` Navigate to a destination from the current navigation graph. This supports both navigating via an `action` and directly navigating to a destination.
`Unit`	`navigate(@IdRes resId: Int, @Nullable args: Bundle?, @Nullable navOptions: NavOptions?)` Navigate to a destination from the current navigation graph. This supports both navigating via an `action` and directly navigating to a destination.
`Unit`	`navigate(@IdRes resId: Int, @Nullable args: Bundle?, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)` Navigate to a destination from the current navigation graph. This supports both navigating via an `action` and directly navigating to a destination.
`Unit`	`navigate(@NonNull deepLink: Uri)` Navigate to a destination via the given deep link `Uri`. `NavDestination#hasDeepLink(Uri)` should be called on `the navigation graph` prior to calling this method to check if the deep link is valid. If an invalid deep link is given, an `IllegalArgumentException` will be thrown.
`Unit`	`navigate(@NonNull deepLink: Uri, @Nullable navOptions: NavOptions?)` Navigate to a destination via the given deep link `Uri`. `NavDestination#hasDeepLink(Uri)` should be called on `the navigation graph` prior to calling this method to check if the deep link is valid. If an invalid deep link is given, an `IllegalArgumentException` will be thrown.
`Unit`	`navigate(@NonNull deepLink: Uri, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)` Navigate to a destination via the given deep link `Uri`. `NavDestination#hasDeepLink(Uri)` should be called on `the navigation graph` prior to calling this method to check if the deep link is valid. If an invalid deep link is given, an `IllegalArgumentException` will be thrown.
`Unit`	`navigate(@NonNull request: NavDeepLinkRequest)` Navigate to a destination via the given `NavDeepLinkRequest`. `NavDestination#hasDeepLink(NavDeepLinkRequest)` should be called on `the navigation graph` prior to calling this method to check if the deep link is valid. If an invalid deep link is given, an `IllegalArgumentException` will be thrown.
`Unit`	`navigate(@NonNull request: NavDeepLinkRequest, @Nullable navOptions: NavOptions?)` Navigate to a destination via the given `NavDeepLinkRequest`. `NavDestination#hasDeepLink(NavDeepLinkRequest)` should be called on `the navigation graph` prior to calling this method to check if the deep link is valid. If an invalid deep link is given, an `IllegalArgumentException` will be thrown.
`Unit`	`navigate(@NonNull request: NavDeepLinkRequest, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)` Navigate to a destination via the given `NavDeepLinkRequest`. `NavDestination#hasDeepLink(NavDeepLinkRequest)` should be called on `the navigation graph` prior to calling this method to check if the deep link is valid. If an invalid deep link is given, an `IllegalArgumentException` will be thrown.
`Unit`	`navigate(@NonNull directions: NavDirections)` Navigate via the given `NavDirections`
`Unit`	`navigate(@NonNull directions: NavDirections, @Nullable navOptions: NavOptions?)` Navigate via the given `NavDirections`
`Unit`	`navigate(@NonNull directions: NavDirections, @NonNull navigatorExtras: Navigator.Extras)` Navigate via the given `NavDirections`
`Boolean`	`navigateUp()` Attempts to navigate up in the navigation hierarchy. Suitable for when the user presses the "Up" button marked with a left (or start)-facing arrow in the upper left (or starting) corner of the app UI. The intended behavior of Up differs from `Back` when the user did not reach the current destination from the application's own task. e.g. if the user is viewing a document or link in the current app in an activity hosted on another app's task where the user clicked the link. In this case the current activity (determined by the context used to create this NavController) will be `finished` and the user will be taken to an appropriate destination in this app on its own task.
`Boolean`	`popBackStack()` Attempts to pop the controller's back stack. Analogous to when the user presses the system `Back` button when the associated navigation host has focus.
`Boolean`	`popBackStack(@IdRes destinationId: Int, inclusive: Boolean)` Attempts to pop the controller's back stack back to a specific destination.
`Unit`	`removeOnDestinationChangedListener(@NonNull listener: NavController.OnDestinationChangedListener)` Removes an `OnDestinationChangedListener` from this controller. It will no longer receive callbacks.
`Unit`	`restoreState(@Nullable navState: Bundle?)` Restores all navigation controller state from a bundle. This should be called before any call to #setGraph. State may be saved to a bundle by calling `saveState()`. Restoring controller state is the responsibility of a `NavHost`.
`Bundle?`	`saveState()` Saves all navigation controller state to a Bundle. State may be restored from a bundle returned from this method by calling `restoreState(Bundle)`. Saving controller state is the responsibility of a `NavHost`.
`Unit`	`setGraph(@NavigationRes graphResId: Int)` Sets the `navigation graph` to the specified resource. Any current navigation graph data (including back stack) will be replaced. The inflated graph can be retrieved via `getGraph()`.
`Unit`	`setGraph(@NavigationRes graphResId: Int, @Nullable startDestinationArgs: Bundle?)` Sets the `navigation graph` to the specified resource. Any current navigation graph data (including back stack) will be replaced. The inflated graph can be retrieved via `getGraph()`.
`Unit`	`setGraph(@NonNull graph: NavGraph)` Sets the `navigation graph` to the specified graph. Any current navigation graph data (including back stack) will be replaced. The graph can be retrieved later via `getGraph()`.
`Unit`	`setGraph(@NonNull graph: NavGraph, @Nullable startDestinationArgs: Bundle?)` Sets the `navigation graph` to the specified graph. Any current navigation graph data (including back stack) will be replaced. The graph can be retrieved later via `getGraph()`.

Public constructors

<init>

NavHostController(@NonNull context: Context)

Construct a new controller for a given Context suitable for use in a NavHost. Controllers should not be used outside of their context and retain a hard reference to the context supplied. If you need a global controller, pass Context#getApplicationContext().

Note that controllers that are not constructed with an Activity context (or a wrapped activity context) will only be able to navigate to new tasks or new document tasks when navigating to new activities.

Parameters
`context`	Context: context for this controller

Public methods

enableOnBackPressed

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

fun setLifecycleOwner(@NonNull owner: LifecycleOwner): Unit

Sets the host's LifecycleOwner.

Parameters
`owner`	LifecycleOwner: The `LifecycleOwner` associated with the containing `NavHost`.

See Also

NavHostController#setOnBackPressedDispatcher(OnBackPressedDispatcher)

setOnBackPressedDispatcher

fun setOnBackPressedDispatcher(@NonNull 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(LifecycleOwner) 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(boolean).

Parameters
`dispatcher`	OnBackPressedDispatcher: The `OnBackPressedDispatcher` associated with the containing `NavHost`.

Exceptions
`IllegalStateException`	if you have not called `setLifecycleOwner(LifecycleOwner)` before calling this method.

See Also

#setLifecycleOwner(LifecycleOwner)

setViewModelStore

fun setViewModelStore(@NonNull 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(int) 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

Exceptions
`IllegalStateException`	if this method is called when graph was already set via `setGraph(int)` or similar methods.