NavController

Kotlin |Java

open class NavController

kotlin.Any
↳	androidx.navigation.NavController

Known Direct Subclasses

NavHostController

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

Known Indirect Subclasses

TestNavHostController

Subclass of NavHostController that offers additional APIs for testing Navigation.

NavController manages app navigation within a NavHost.

Apps will generally obtain a controller directly from a host, or by using one of the utility methods on the Navigation class rather than create a controller directly.

Navigation flows and destinations are determined by the navigation graph owned by the controller. These graphs are typically inflated from an Android resource, but, like views, they can also be constructed or combined programmatically or for the case of dynamic navigation structure. (For example, if the navigation structure of the application is determined by live data obtained' from a remote server.)

Summary

Nested classes
abstract	`OnDestinationChangedListener` OnDestinationChangedListener receives a callback when the `getCurrentDestination()` or its arguments change.

Constants
static String	`KEY_DEEP_LINK_INTENT` The `Intent` that triggered a deep link to the current destination.

Public constructors
`<init>(@NonNull context: Context)` Constructs a new controller for a given `Context`.

Public methods
open Unit	`addOnDestinationChangedListener(@NonNull listener: NavController.OnDestinationChangedListener)` Adds an `OnDestinationChangedListener` to this controller to receive a callback whenever the `getCurrentDestination()` or its arguments change.
open NavDeepLinkBuilder	`createDeepLink()` Create a deep link to a destination within this NavController.
open NavBackStackEntry	`getBackStackEntry(@IdRes destinationId: Int)` Gets the topmost `NavBackStackEntry` for a destination id.
open NavBackStackEntry?	`getCurrentBackStackEntry()` Gets the topmost `NavBackStackEntry`.
open NavDestination?	`getCurrentDestination()` Gets the current destination.
open NavGraph	`getGraph()` Gets the topmost navigation graph associated with this NavController.
open NavInflater	`getNavInflater()` Returns the `inflater` for this controller.
open NavigatorProvider	`getNavigatorProvider()` Retrieve the NavController's `NavigatorProvider`.
open NavBackStackEntry?	`getPreviousBackStackEntry()` Gets the previous visible `NavBackStackEntry`.
open ViewModelStoreOwner	`getViewModelStoreOwner(@IdRes navGraphId: Int)` Gets the `ViewModelStoreOwner` for a NavGraph.
open Boolean	`handleDeepLink(@Nullable intent: Intent?)` Checks the given Intent for a Navigation deep link and navigates to the deep link if present.
open Unit	`navigate(@IdRes resId: Int)` Navigate to a destination from the current navigation graph.
open Unit	`navigate(@IdRes resId: Int, @Nullable args: Bundle?)` Navigate to a destination from the current navigation graph.
open Unit	`navigate(@IdRes resId: Int, @Nullable args: Bundle?, @Nullable navOptions: NavOptions?)` Navigate to a destination from the current navigation graph.
open Unit	`navigate(@IdRes resId: Int, @Nullable args: Bundle?, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)` Navigate to a destination from the current navigation graph.
open Unit	`navigate(@NonNull deepLink: Uri)` Navigate to a destination via the given deep link `Uri`.
open Unit	`navigate(@NonNull deepLink: Uri, @Nullable navOptions: NavOptions?)` Navigate to a destination via the given deep link `Uri`.
open Unit	`navigate(@NonNull deepLink: Uri, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)` Navigate to a destination via the given deep link `Uri`.
open Unit	`navigate(@NonNull request: NavDeepLinkRequest)` Navigate to a destination via the given `NavDeepLinkRequest`.
open Unit	`navigate(@NonNull request: NavDeepLinkRequest, @Nullable navOptions: NavOptions?)` Navigate to a destination via the given `NavDeepLinkRequest`.
open Unit	`navigate(@NonNull request: NavDeepLinkRequest, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)` Navigate to a destination via the given `NavDeepLinkRequest`.
open Unit	`navigate(@NonNull directions: NavDirections)` Navigate via the given `NavDirections`
open Unit	`navigate(@NonNull directions: NavDirections, @Nullable navOptions: NavOptions?)` Navigate via the given `NavDirections`
open Unit	`navigate(@NonNull directions: NavDirections, @NonNull navigatorExtras: Navigator.Extras)` Navigate via the given `NavDirections`
open Boolean	`navigateUp()` Attempts to navigate up in the navigation hierarchy.
open Boolean	`popBackStack()` Attempts to pop the controller's back stack.
open Boolean	`popBackStack(@IdRes destinationId: Int, inclusive: Boolean)` Attempts to pop the controller's back stack back to a specific destination.
open Unit	`removeOnDestinationChangedListener(@NonNull listener: NavController.OnDestinationChangedListener)` Removes an `OnDestinationChangedListener` from this controller.
open Unit	`restoreState(@Nullable navState: Bundle?)` Restores all navigation controller state from a bundle.
open Bundle?	`saveState()` Saves all navigation controller state to a Bundle.
open Unit	`setGraph(@NavigationRes graphResId: Int)` Sets the `navigation graph` to the specified resource.
open Unit	`setGraph(@NavigationRes graphResId: Int, @Nullable startDestinationArgs: Bundle?)` Sets the `navigation graph` to the specified resource.
open Unit	`setGraph(@NonNull graph: NavGraph)` Sets the `navigation graph` to the specified graph.
open Unit	`setGraph(@NonNull graph: NavGraph, @Nullable startDestinationArgs: Bundle?)` Sets the `navigation graph` to the specified graph.

Extension functions

From androidx.navigation

NavGraph

NavController.createGraph(@IdRes id: Int = 0, @IdRes startDestination: Int, builder: NavGraphBuilder.() -> Unit)

Construct a new NavGraph

From androidx.navigation.dynamicfeatures

NavGraph

NavController.createGraph(@IdRes id: Int = 0, @IdRes startDestination: Int, builder: DynamicNavGraphBuilder.() -> Unit)

Construct a new androidx.navigation.NavGraph that supports dynamic navigation destinations

From androidx.navigation.ui

Boolean	`NavController.navigateUp(drawerLayout: Openable?)` Handles the Up button by delegating its behavior to the given NavController.
Boolean	`NavController.navigateUp(appBarConfiguration: AppBarConfiguration)` Handles the Up button by delegating its behavior to the given NavController.

Constants

KEY_DEEP_LINK_INTENT

@NonNull static val KEY_DEEP_LINK_INTENT: String

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

Value: "android-support-nav:controller:deepLinkIntent"

Public constructors

<init>

NavController(@NonNull context: Context)

Constructs a new controller for a given Context. 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().

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.

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

addOnDestinationChangedListener

open fun addOnDestinationChangedListener(@NonNull listener: NavController.OnDestinationChangedListener): Unit

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.

Parameters
`listener`	NavController.OnDestinationChangedListener: the listener to receive events

createDeepLink

@NonNull open fun createDeepLink(): NavDeepLinkBuilder

Create a deep link to a destination within this NavController.

Return
`NavDeepLinkBuilder`	a `NavDeepLinkBuilder` suitable for constructing a deep link

getBackStackEntry

@NonNull open fun getBackStackEntry(@IdRes destinationId: Int): NavBackStackEntry

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.

Parameters
`destinationId`	Int: ID of a destination that exists on the back stack

Exceptions
`IllegalArgumentException`	if the destination is not on the back stack

getCurrentBackStackEntry

@Nullable open fun getCurrentBackStackEntry(): NavBackStackEntry?

Gets the topmost NavBackStackEntry.

Return
`NavBackStackEntry?`	the topmost entry on the back stack or null if the back stack is empty

getCurrentDestination

@Nullable open fun getCurrentDestination(): NavDestination?

Gets the current destination.

getGraph

@NonNull open fun getGraph(): NavGraph

Gets the topmost navigation graph associated with this NavController.

Exceptions
`IllegalStateException`	if called before `setGraph()`.

See Also

#setGraph(int)
#setGraph(NavGraph)

getNavInflater

@NonNull open fun getNavInflater(): NavInflater

Returns the inflater for this controller.

Return
`NavInflater`	inflater for loading navigation resources

getNavigatorProvider

@NonNull open fun getNavigatorProvider(): NavigatorProvider

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.

Return
`NavigatorProvider`	The `NavigatorProvider` used by this NavController.

getPreviousBackStackEntry

@Nullable open fun getPreviousBackStackEntry(): NavBackStackEntry?

Gets the previous visible NavBackStackEntry.

This skips over any NavBackStackEntry that is associated with a NavGraph.

Return
`NavBackStackEntry?`	the previous visible entry on the back stack or null if the back stack has less than two visible entries

getViewModelStoreOwner

@NonNull open fun getViewModelStoreOwner(@IdRes navGraphId: Int): ViewModelStoreOwner

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.

Parameters
`navGraphId`	Int: ID of a NavGraph that exists on the back stack

Exceptions
`IllegalStateException`	if called before the `NavHost` has called `NavHostController#setViewModelStore`.
`IllegalArgumentException`	if the NavGraph is not on the back stack

handleDeepLink

open fun handleDeepLink(@Nullable intent: Intent?): Boolean

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:

NavDeepLinkBuilder

createDeepLink()

data Uri

NavDeepLinks

NavDestination#addDeepLink(NavDeepLink)

The navigation graph should be set before calling this method.

Parameters
`intent`	Intent?: The Intent that may contain a valid deep link

Return
`Boolean`	True if the navigation controller found a valid deep link and navigated to it.

See Also

NavDestination#addDeepLink(NavDeepLink)

navigate

open fun navigate(@IdRes resId: Int): Unit

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
`resId`	Int: an `action` id or a destination id to navigate to

navigate

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

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
`resId`	Int: an `action` id or a destination id to navigate to
`args`	Bundle?: arguments to pass to the destination

navigate

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

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
`resId`	Int: an `action` id or a destination id to navigate to
`args`	Bundle?: arguments to pass to the destination
`navOptions`	NavOptions?: special options for this navigation operation

navigate

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

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
`resId`	Int: an `action` id or a destination id to navigate to
`args`	Bundle?: arguments to pass to the destination
`navOptions`	NavOptions?: special options for this navigation operation
`navigatorExtras`	Navigator.Extras?: extras to pass to the Navigator

navigate

open fun navigate(@NonNull deepLink: Uri): Unit

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.

Parameters
`deepLink`	Uri: deepLink to the destination reachable from the current NavGraph

See Also

#navigate(NavDeepLinkRequest)

navigate

open fun navigate(
    @NonNull deepLink: Uri, 
    @Nullable navOptions: NavOptions?
): Unit

Parameters
`deepLink`	Uri: deepLink to the destination reachable from the current NavGraph
`navOptions`	NavOptions?: special options for this navigation operation

See Also

#navigate(NavDeepLinkRequest, NavOptions)

navigate

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

Parameters
`deepLink`	Uri: deepLink to the destination reachable from the current NavGraph
`navOptions`	NavOptions?: special options for this navigation operation
`navigatorExtras`	Navigator.Extras?: extras to pass to the Navigator

See Also

#navigate(NavDeepLinkRequest, NavOptions, Navigator.Extras)

navigate

open fun navigate(@NonNull request: NavDeepLinkRequest): Unit

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.

Parameters
`request`	NavDeepLinkRequest: deepLinkRequest to the destination reachable from the current NavGraph

navigate

open fun navigate(
    @NonNull request: NavDeepLinkRequest, 
    @Nullable navOptions: NavOptions?
): Unit

Parameters
`request`	NavDeepLinkRequest: deepLinkRequest to the destination reachable from the current NavGraph
`navOptions`	NavOptions?: special options for this navigation operation

navigate

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

Parameters
`request`	NavDeepLinkRequest: deepLinkRequest to the destination reachable from the current NavGraph
`navOptions`	NavOptions?: special options for this navigation operation
`navigatorExtras`	Navigator.Extras?: extras to pass to the Navigator

navigate

open fun navigate(@NonNull directions: NavDirections): Unit

Navigate via the given NavDirections

Parameters
`directions`	NavDirections: directions that describe this navigation operation

navigate

open fun navigate(
    @NonNull directions: NavDirections, 
    @Nullable navOptions: NavOptions?
): Unit

Navigate via the given NavDirections

Parameters
`directions`	NavDirections: directions that describe this navigation operation
`navOptions`	NavOptions?: special options for this navigation operation

navigate

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

Navigate via the given NavDirections

Parameters
`directions`	NavDirections: directions that describe this navigation operation
`navigatorExtras`	Navigator.Extras: extras to pass to the `Navigator`

navigateUp

open fun navigateUp(): Boolean

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.

Return
`Boolean`	true if navigation was successful, false otherwise

popBackStack

open fun popBackStack(): Boolean

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.

Return
`Boolean`	true if the stack was popped and the user has been navigated to another destination, false otherwise

popBackStack

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

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

Parameters
`destinationId`	Int: The topmost destination to retain
`inclusive`	Boolean: Whether the given destination should also be popped.

Return
`Boolean`	true if the stack was popped at least once and the user has been navigated to another destination, false otherwise

removeOnDestinationChangedListener

open fun removeOnDestinationChangedListener(@NonNull listener: NavController.OnDestinationChangedListener): Unit

Removes an OnDestinationChangedListener from this controller. It will no longer receive callbacks.

Parameters
`listener`	NavController.OnDestinationChangedListener: the listener to remove

restoreState

@CallSuper open fun restoreState(@Nullable navState: Bundle?): Unit

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.

Parameters
`navState`	Bundle?: state bundle to restore

saveState

@CallSuper @Nullable open fun saveState(): Bundle?

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.

Return
`Bundle?`	saved state for this controller

setGraph

@CallSuper open fun setGraph(@NavigationRes graphResId: Int): Unit

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().

Parameters
`graphResId`	Int: resource id of the navigation graph to inflate

See Also

#getNavInflater()
#setGraph(NavGraph)
#getGraph

setGraph

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

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().

Parameters
`graphResId`	Int: resource id of the navigation graph to inflate
`startDestinationArgs`	Bundle?: arguments to send to the start destination of the graph

See Also

#getNavInflater()
#setGraph(NavGraph, Bundle)
#getGraph

setGraph

@CallSuper open fun setGraph(@NonNull graph: NavGraph): Unit

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().

Parameters
`graph`	NavGraph: graph to set

See Also

#setGraph(int)
#getGraph

setGraph

@CallSuper open fun setGraph(
    @NonNull graph: NavGraph, 
    @Nullable startDestinationArgs: Bundle?
): Unit

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().

Parameters
`graph`	NavGraph: graph to set

See Also

#setGraph(int, Bundle)
#getGraph