Google is committed to advancing racial equity for Black communities. See how.

NavController

open class NavController
kotlin.Any
   ↳ androidx.navigation.NavController

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 receives a callback when the getCurrentDestination() or its arguments change.

Constants
static String

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

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

open NavDeepLinkBuilder

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?

Gets the topmost NavBackStackEntry.

open NavDestination?

Gets the current destination.

open NavGraph

Gets the topmost navigation graph associated with this NavController.

open NavInflater

Returns the inflater for this controller.

open NavigatorProvider

Retrieve the NavController's NavigatorProvider.

open NavBackStackEntry?

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

Attempts to navigate up in the navigation hierarchy.

open Boolean

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

Removes an OnDestinationChangedListener from this controller.

open Unit
restoreState(@Nullable navState: Bundle?)

Restores all navigation controller state from a bundle.

open Bundle?

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.compose
NavGraph
NavController.createGraph(startDestination: String, route: String? = null, builder: NavGraphBuilder.() -> Unit)

Construct a new NavGraph

State<NavBackStackEntry?>

Gets the current navigation back stack entry as a MutableState.

Unit
NavController.navigate(route: String, builder: NavOptionsBuilder.() -> Unit = {})

Navigate to a route in the current 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

Handles the Up button by delegating its behavior to the given NavController.

Boolean

Handles the Up button by delegating its behavior to the given NavController.

Constants

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

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
open fun handleDeepLink(@Nullable intent: Intent?): Boolean

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