NavController

Artifact: androidx.navigation:navigation-runtime

View Source

Added in 1.0.0

---

Kotlin |Java

public class NavController

Known direct subclasses

NavHostController

NavHostController

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

Known indirect subclasses

TestNavHostController

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 types
public fun interface NavController.OnDestinationChangedListener OnDestinationChangedListener receives a callback when the currentDestination or its arguments change.

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

Public constructors
NavController(@NonNull Context context)

Public methods
void	addOnDestinationChangedListener(     @NonNull NavController.OnDestinationChangedListener listener ) Adds an OnDestinationChangedListener to this controller to receive a callback whenever the currentDestination or its arguments change.
final boolean	@MainThread <T extends Object> clearBackStack() Clears any saved state associated with KClass T that was previously saved via popBackStack when using a saveState value of true.
final boolean	@MainThread clearBackStack(@IdRes int destinationId) Clears any saved state associated with destinationId that was previously saved via popBackStack when using a saveState value of true.
final boolean	@MainThread <T extends Object> clearBackStack(@NonNull KClass<@NonNull T> route) Clears any saved state associated with KClass route that was previously saved via popBackStack when using a saveState value of true.
final boolean	@MainThread <T extends Object> clearBackStack(@NonNull T route) Clears any saved state associated with KClass T that was previously saved via popBackStack when using a saveState value of true.
final boolean	@MainThread clearBackStack(@NonNull String route) Clears any saved state associated with route that was previously saved via popBackStack when using a saveState value of true.
@NonNull NavDeepLinkBuilder	createDeepLink() Create a deep link to a destination within this NavController.
static final void	@NavDeepLinkSaveStateControl enableDeepLinkSaveState(boolean saveState) By default, handleDeepLink will automatically add calls to NavOptions.Builder.setPopUpTo with a saveState of true when the deep link takes you to another graph (e.g., a different navigation graph than the one your start destination is in).
final @NonNull NavBackStackEntry	<T extends Object> getBackStackEntry() Gets the topmost NavBackStackEntry for a route from KClass.
@NonNull NavBackStackEntry	getBackStackEntry(@IdRes int destinationId) Gets the topmost NavBackStackEntry for a destination id.
final @NonNull NavBackStackEntry	<T extends Object> getBackStackEntry(@NonNull KClass<@NonNull T> route) Gets the topmost NavBackStackEntry for a route from KClass.
final @NonNull NavBackStackEntry	<T extends Object> getBackStackEntry(@NonNull T route) Gets the topmost NavBackStackEntry for a route from an Object.
final @NonNull NavBackStackEntry	getBackStackEntry(@NonNull String route) Gets the topmost NavBackStackEntry for a route.
NavBackStackEntry	getCurrentBackStackEntry() The topmost NavBackStackEntry.
final @NonNull Flow<@NonNull NavBackStackEntry>	getCurrentBackStackEntryFlow() A Flow that will emit the currently active NavBackStackEntry whenever it changes.
NavDestination	getCurrentDestination() The current destination.
@NonNull NavGraph	@MainThread getGraph() The topmost navigation graph associated with this NavController.
@NonNull NavInflater	getNavInflater() The inflater for this controller.
@NonNull NavigatorProvider	getNavigatorProvider() The NavController's NavigatorProvider.
NavBackStackEntry	getPreviousBackStackEntry() The previous visible NavBackStackEntry.
@NonNull ViewModelStoreOwner	getViewModelStoreOwner(@IdRes int navGraphId) Gets the ViewModelStoreOwner for a NavGraph.
final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>>	getVisibleEntries() A StateFlow that will emit the currently visible NavBackStackEntries whenever they change.
boolean	@MainThread handleDeepLink(Intent intent) Checks the given Intent for a Navigation deep link and navigates to the deep link if present.
final boolean	@MainThread handleDeepLink(@NonNull NavDeepLinkRequest request) Checks the given NavDeepLinkRequest for a Navigation deep link and navigates to the destination if present.
void	@MainThread navigate(@NonNull Uri deepLink) Navigate to a destination via the given deep link Uri.
void	@MainThread navigate(@NonNull NavDirections directions) Navigate via the given NavDirections
void	@MainThread navigate(@NonNull NavDeepLinkRequest request) Navigate to a destination via the given NavDeepLinkRequest.
void	@MainThread navigate(@IdRes int resId) Navigate to a destination from the current navigation graph.
void	@MainThread navigate(@NonNull Uri deepLink, NavOptions navOptions) Navigate to a destination via the given deep link Uri.
void	@MainThread navigate(@NonNull NavDirections directions, NavOptions navOptions) Navigate via the given NavDirections
void	@MainThread navigate(     @NonNull NavDirections directions,     @NonNull Navigator.Extras navigatorExtras ) Navigate via the given NavDirections
void	@MainThread navigate(@NonNull NavDeepLinkRequest request, NavOptions navOptions) Navigate to a destination via the given NavDeepLinkRequest.
void	@MainThread navigate(@IdRes int resId, Bundle args) Navigate to a destination from the current navigation graph.
final void	@MainThread <T extends Object> navigate(     @NonNull T route,     @ExtensionFunctionType @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder ) Navigate to a route from an Object in the current NavGraph.
final void	@MainThread navigate(     @NonNull String route,     @ExtensionFunctionType @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder ) Navigate to a route in the current NavGraph.
void	@MainThread navigate(     @NonNull Uri deepLink,     NavOptions navOptions,     Navigator.Extras navigatorExtras ) Navigate to a destination via the given deep link Uri.
void	@MainThread navigate(     @NonNull NavDeepLinkRequest request,     NavOptions navOptions,     Navigator.Extras navigatorExtras ) Navigate to a destination via the given NavDeepLinkRequest.
void	@MainThread navigate(@IdRes int resId, Bundle args, NavOptions navOptions) Navigate to a destination from the current navigation graph.
final void	@MainThread <T extends Object> navigate(     @NonNull T route,     NavOptions navOptions,     Navigator.Extras navigatorExtras ) Navigate to a route from an Object in the current NavGraph.
final void	@MainThread navigate(     @NonNull String route,     NavOptions navOptions,     Navigator.Extras navigatorExtras ) Navigate to a route in the current NavGraph.
void	@MainThread navigate(     @IdRes int resId,     Bundle args,     NavOptions navOptions,     Navigator.Extras navigatorExtras ) Navigate to a destination from the current navigation graph.
boolean	@MainThread navigateUp() Attempts to navigate up in the navigation hierarchy.
boolean	@MainThread popBackStack() Attempts to pop the controller's back stack.
boolean	@MainThread popBackStack(@IdRes int destinationId, boolean inclusive) Attempts to pop the controller's back stack back to a specific destination.
final boolean	@MainThread <T extends Object> popBackStack(boolean inclusive, boolean saveState) Attempts to pop the controller's back stack back to a specific destination.
boolean	@MainThread popBackStack(     @IdRes int destinationId,     boolean inclusive,     boolean saveState ) Attempts to pop the controller's back stack back to a specific destination.
final boolean	@MainThread <T extends Object> popBackStack(     @NonNull KClass<@NonNull T> route,     boolean inclusive,     boolean saveState ) Attempts to pop the controller's back stack back to a specific destination.
final boolean	@MainThread <T extends Object> popBackStack(     @NonNull T route,     boolean inclusive,     boolean saveState ) Attempts to pop the controller's back stack back to a specific destination.
final boolean	@MainThread popBackStack(@NonNull String route, boolean inclusive, boolean saveState) Attempts to pop the controller's back stack back to a specific destination.
void	removeOnDestinationChangedListener(     @NonNull NavController.OnDestinationChangedListener listener ) Removes an OnDestinationChangedListener from this controller.
void	@CallSuper restoreState(Bundle navState) Restores all navigation controller state from a bundle.
Bundle	@CallSuper saveState() Saves all navigation controller state to a Bundle.
void	@MainThread @CallSuper setGraph(@NonNull NavGraph graph) The topmost navigation graph associated with this NavController.
void	@MainThread @CallSuper setGraph(@NavigationRes int graphResId) Sets the navigation graph to the specified resource.
void	@MainThread @CallSuper setGraph(@NonNull NavGraph graph, Bundle startDestinationArgs) Sets the navigation graph to the specified graph.
void	@MainThread @CallSuper setGraph(@NavigationRes int graphResId, Bundle startDestinationArgs) Sets the navigation graph to the specified resource.

Extension functions
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @IdRes int id,     @IdRes int startDestination,     @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder ) This method is deprecated. Use routes to create your NavGraph instead
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @IdRes int id,     @IdRes int startDestination,     @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder ) This method is deprecated. Use routes to create your dynamic NavGraph instead
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @NonNull String startDestination,     String route,     @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder ) Construct a new NavGraph
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @NonNull String startDestination,     String route,     @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder ) Construct a new androidx.navigation.NavGraph that supports dynamic navigation destinations
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @NonNull Object startDestination,     KClass<@NonNull ?> route,     @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,     @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder ) Construct a new NavGraph
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @NonNull Object startDestination,     KClass<@NonNull ?> route,     @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,     @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder ) Construct a new androidx.navigation.NavGraph that supports dynamic navigation destinations
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @NonNull KClass<@NonNull ?> startDestination,     KClass<@NonNull ?> route,     @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,     @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder ) Construct a new NavGraph
final @NonNull NavGraph	NavControllerKt.createGraph(     @NonNull NavController receiver,     @NonNull KClass<@NonNull ?> startDestination,     KClass<@NonNull ?> route,     @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,     @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder ) Construct a new androidx.navigation.NavGraph that supports dynamic navigation destinations
final boolean	NavControllerKt.navigateUp(     @NonNull NavController receiver,     @NonNull AppBarConfiguration appBarConfiguration ) Handles the Up button by delegating its behavior to the given NavController.
final boolean	NavControllerKt.navigateUp(     @NonNull NavController receiver,     Openable drawerLayout ) Handles the Up button by delegating its behavior to the given NavController.

Constants

KEY_DEEP_LINK_INTENT

public static final @NonNull String KEY_DEEP_LINK_INTENT

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

Public constructors

NavController

Added in 1.0.0

public NavController(@NonNull Context context)

Public methods

addOnDestinationChangedListener

Added in 1.0.0

public void addOnDestinationChangedListener(
    @NonNull NavController.OnDestinationChangedListener listener
)

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

The current destination, if any, will be immediately sent to your listener.

Parameters
@NonNull NavController.OnDestinationChangedListener listener	the listener to receive events

clearBackStack

@MainThread
public final boolean <T extends Object> clearBackStack()

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

Parameters
<T extends Object>	The route from the KClass of the destination previously used with popBackStack with a saveStatevalue of true. The target NavDestination must have been created with route from KClass.

Returns
boolean	true if the saved state of the stack associated with T was cleared.

clearBackStack

Added in 2.4.0

@MainThread
public final boolean clearBackStack(@IdRes int destinationId)

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

Parameters
@IdRes int destinationId	The ID of the destination previously used with popBackStack with a saveStatevalue of true

Returns
boolean	true if the saved state of the stack associated with destinationId was cleared.

clearBackStack

Added in 2.9.0-alpha04

@MainThread
public final boolean <T extends Object> clearBackStack(@NonNull KClass<@NonNull T> route)

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

Parameters
@NonNull KClass<@NonNull T> route	The route from the KClass of the destination previously used with popBackStack with a saveStatevalue of true. The target NavDestination must have been created with route from KClass.

Returns
boolean	true if the saved state of the stack associated with route was cleared.

clearBackStack

Added in 2.8.0

@MainThread
public final boolean <T extends Object> clearBackStack(@NonNull T route)

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

Parameters
@NonNull T route	The route from an Object of the destination previously used with popBackStack with a saveStatevalue of true. The target NavDestination must have been created with route from KClass.

Returns
boolean	true if the saved state of the stack associated with T was cleared.

clearBackStack

Added in 2.4.0

@MainThread
public final boolean clearBackStack(@NonNull String route)

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

Parameters
@NonNull String route	The route of the destination previously used with popBackStack with a saveState value of true. May contain filled in arguments as long as it is exact match with route used with popBackStack.

Returns
boolean	true if the saved state of the stack associated with route was cleared.

createDeepLink

Added in 1.0.0

public @NonNull NavDeepLinkBuilder createDeepLink()

Create a deep link to a destination within this NavController.

Returns
@NonNull NavDeepLinkBuilder	a NavDeepLinkBuilder suitable for constructing a deep link

enableDeepLinkSaveState

Added in 2.4.0

@NavDeepLinkSaveStateControl
public static final void enableDeepLinkSaveState(boolean saveState)

By default, handleDeepLink will automatically add calls to NavOptions.Builder.setPopUpTo with a saveState of true when the deep link takes you to another graph (e.g., a different navigation graph than the one your start destination is in).

You can disable this behavior by passing false for saveState.

getBackStackEntry

public final @NonNull NavBackStackEntry <T extends Object> getBackStackEntry()

Gets the topmost NavBackStackEntry for a route from KClass.

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
<T extends Object>	route from the KClass of a destination that exists on the back stack. The target NavBackStackEntry's NavDestination must have been created with route from KClass.

Throws
kotlin.IllegalArgumentException	if the destination is not on the back stack

getBackStackEntry

Added in 2.2.0

public @NonNull NavBackStackEntry getBackStackEntry(@IdRes int destinationId)

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
@IdRes int destinationId	ID of a destination that exists on the back stack

Throws
kotlin.IllegalArgumentException	if the destination is not on the back stack

getBackStackEntry

Added in 2.9.0-alpha04

public final @NonNull NavBackStackEntry <T extends Object> getBackStackEntry(@NonNull KClass<@NonNull T> route)

Gets the topmost NavBackStackEntry for a route from KClass.

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
@NonNull KClass<@NonNull T> route	route from the KClass of destination T that exists on the back stack. The target NavBackStackEntry's NavDestination must have been created with route from KClass.

Throws
kotlin.IllegalArgumentException	if the destination is not on the back stack

getBackStackEntry

Added in 2.8.0

public final @NonNull NavBackStackEntry <T extends Object> getBackStackEntry(@NonNull T route)

Gets the topmost NavBackStackEntry for a route from an Object.

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
@NonNull T route	route from an Object of a destination that exists on the back stack. The target NavBackStackEntry's NavDestination must have been created with route from KClass.

Throws
kotlin.IllegalArgumentException	if the destination is not on the back stack

getBackStackEntry

Added in 2.4.0

public final @NonNull NavBackStackEntry getBackStackEntry(@NonNull String route)

Gets the topmost NavBackStackEntry for a route.

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
@NonNull String route	route of a destination that exists on the back stack. May contain filled in arguments as long as it is exact match with route used to navigate.

Throws
kotlin.IllegalArgumentException	if the destination is not on the back stack

getCurrentBackStackEntry

Added in 2.3.0

public NavBackStackEntry getCurrentBackStackEntry()

The topmost NavBackStackEntry.

Returns
NavBackStackEntry	the topmost entry on the back stack or null if the back stack is empty

getCurrentBackStackEntryFlow

Added in 2.4.0

public final @NonNull Flow<@NonNull NavBackStackEntry> getCurrentBackStackEntryFlow()

A Flow that will emit the currently active NavBackStackEntry whenever it changes. If there is no active NavBackStackEntry, no item will be emitted.

getCurrentDestination

Added in 1.0.0

public NavDestination getCurrentDestination()

The current destination.

getGraph

Added in 1.0.0

@MainThread
public @NonNull NavGraph getGraph()

The topmost navigation graph associated with this NavController.

When this is set any current navigation graph data (including back stack) will be replaced.

Throws
kotlin.IllegalStateException	if called before setGraph().

See also
setGraph

getNavInflater

Added in 1.0.0

public @NonNull NavInflater getNavInflater()

The inflater for this controller.

Returns
@NonNull NavInflater	inflater for loading navigation resources

getNavigatorProvider

Added in 1.0.0

public @NonNull NavigatorProvider getNavigatorProvider()

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.

This can only be set before the graph is set via setGraph().

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.

Throws
kotlin.IllegalStateException	If this set called after setGraph()

getPreviousBackStackEntry

Added in 2.3.0

public NavBackStackEntry getPreviousBackStackEntry()

The previous visible NavBackStackEntry.

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

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

getViewModelStoreOwner

Added in 2.1.0

public @NonNull ViewModelStoreOwner getViewModelStoreOwner(@IdRes int navGraphId)

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
@IdRes int navGraphId	ID of a NavGraph that exists on the back stack

Throws
kotlin.IllegalStateException	if called before the NavHost has called NavHostController.setViewModelStore.
kotlin.IllegalArgumentException	if the NavGraph is not on the back stack

getVisibleEntries

Added in 2.4.0

public final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>> getVisibleEntries()

A StateFlow that will emit the currently visible NavBackStackEntries whenever they change. If there is no visible NavBackStackEntry, this will be set to an empty list.

• CREATED entries are listed first and include all entries that are in the process of completing their exit transition. Note that this can include entries that have been popped off the Navigation back stack.

• STARTED entries on the back stack are next and include all entries that are running their enter transition and entries whose destination is partially covered by a FloatingWindow destination

• The last entry in the list is the topmost entry in the back stack and is in the RESUMED state only if its enter transition has completed. Otherwise it too will be STARTED.

Note that the Lifecycle of any entry cannot be higher than the containing Activity/Fragment - if the Activity is not RESUMED, no entry will be RESUMED, no matter what the transition state is.

handleDeepLink

Added in 1.0.0

@MainThread
public boolean handleDeepLink(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.

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.

The navigation graph should be set before calling this method.

Parameters
Intent intent	The Intent that may contain a valid deep link

Returns
boolean	True if the navigation controller found a valid deep link and navigated to it.

Throws
kotlin.IllegalStateException	if deep link cannot be accessed from the current destination

See also
addDeepLink

handleDeepLink

Added in 2.9.0-alpha04

@MainThread
public final boolean handleDeepLink(@NonNull NavDeepLinkRequest request)

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

The navigation graph should be set before calling this method.

Parameters
@NonNull NavDeepLinkRequest request	The request that contains a valid deep link, an action or a mimeType.

Returns
boolean	True if the navigation controller found a valid deep link and navigated to it.

Throws
kotlin.IllegalStateException	if deep link cannot be accessed from the current destination

See also
addDeepLink

navigate

Added in 2.1.0

@MainThread
public void navigate(@NonNull Uri deepLink)

Navigate to a destination via the given deep link Uri. NavDestination.hasDeepLink 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
@NonNull Uri deepLink	deepLink to the destination reachable from the current NavGraph

See also
navigate

navigate

Added in 1.0.0

@MainThread
public void navigate(@NonNull NavDirections directions)

Navigate via the given NavDirections

Parameters
@NonNull NavDirections directions	directions that describe this navigation operation

navigate

Added in 2.3.0

@MainThread
public void navigate(@NonNull NavDeepLinkRequest request)

Navigate to a destination via the given NavDeepLinkRequest. NavDestination.hasDeepLink 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
@NonNull NavDeepLinkRequest request	deepLinkRequest to the destination reachable from the current NavGraph

Throws
kotlin.IllegalArgumentException	if the given deep link request is invalid

navigate

Added in 1.0.0

@MainThread
public void navigate(@IdRes int resId)

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

Parameters
@IdRes int resId	an action id or a destination id to navigate to

Throws
kotlin.IllegalStateException	if there is no current navigation node
kotlin.IllegalArgumentException	if the desired destination cannot be found from the current destination

navigate

Added in 2.1.0

@MainThread
public void navigate(@NonNull Uri deepLink, NavOptions navOptions)

Navigate to a destination via the given deep link Uri. NavDestination.hasDeepLink 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
@NonNull Uri deepLink	deepLink to the destination reachable from the current NavGraph
NavOptions navOptions	special options for this navigation operation

See also
navigate

navigate

Added in 1.0.0

@MainThread
public void navigate(@NonNull NavDirections directions, NavOptions navOptions)

Navigate via the given NavDirections

Parameters
@NonNull NavDirections directions	directions that describe this navigation operation
NavOptions navOptions	special options for this navigation operation

navigate

Added in 1.0.0

@MainThread
public void navigate(
    @NonNull NavDirections directions,
    @NonNull Navigator.Extras navigatorExtras
)

Navigate via the given NavDirections

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

navigate

Added in 2.3.0

@MainThread
public void navigate(@NonNull NavDeepLinkRequest request, NavOptions navOptions)

Navigate to a destination via the given NavDeepLinkRequest. NavDestination.hasDeepLink 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
@NonNull NavDeepLinkRequest request	deepLinkRequest to the destination reachable from the current NavGraph
NavOptions navOptions	special options for this navigation operation

Throws
kotlin.IllegalArgumentException	if the given deep link request is invalid

navigate

Added in 1.0.0

@MainThread
public void navigate(@IdRes int resId, Bundle args)

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

Parameters
@IdRes int resId	an action id or a destination id to navigate to
Bundle args	arguments to pass to the destination

Throws
kotlin.IllegalStateException	if there is no current navigation node
kotlin.IllegalArgumentException	if the desired destination cannot be found from the current destination

navigate

Added in 2.8.0

@MainThread
public final void <T extends Object> navigate(
    @NonNull T route,
    @ExtensionFunctionType @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder
)

Navigate to a route from an Object in the current NavGraph. If an invalid route is given, an IllegalArgumentException will be thrown.

The target NavDestination must have been created with route from a KClass

If given NavOptions pass in NavOptions.restoreState true, any args passed here as part of the route will be overridden by the restored args.

Parameters
@NonNull T route	route from an Object for the destination
@ExtensionFunctionType @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder	DSL for constructing a new NavOptions

Throws
kotlin.IllegalArgumentException	if the given route is invalid

navigate

Added in 2.4.0

@MainThread
public final void navigate(
    @NonNull String route,
    @ExtensionFunctionType @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder
)

Navigate to a route in the current NavGraph. If an invalid route is given, an IllegalArgumentException will be thrown.

If given NavOptions pass in NavOptions.restoreState true, any args passed here as part of the route will be overridden by the restored args.

Parameters
@NonNull String route	route for the destination
@ExtensionFunctionType @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder	DSL for constructing a new NavOptions

Throws
kotlin.IllegalArgumentException	if the given route is invalid

navigate

Added in 2.1.0

@MainThread
public void navigate(
    @NonNull Uri deepLink,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination via the given deep link Uri. NavDestination.hasDeepLink 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
@NonNull Uri deepLink	deepLink to the destination reachable from the current NavGraph
NavOptions navOptions	special options for this navigation operation
Navigator.Extras navigatorExtras	extras to pass to the Navigator

See also
navigate

navigate

Added in 2.3.0

@MainThread
public void navigate(
    @NonNull NavDeepLinkRequest request,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination via the given NavDeepLinkRequest. NavDestination.hasDeepLink 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
@NonNull NavDeepLinkRequest request	deepLinkRequest to the destination reachable from the current NavGraph
NavOptions navOptions	special options for this navigation operation
Navigator.Extras navigatorExtras	extras to pass to the Navigator

Throws
kotlin.IllegalArgumentException	if the given deep link request is invalid

navigate

Added in 1.0.0

@MainThread
public void navigate(@IdRes int resId, Bundle args, NavOptions navOptions)

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

If given NavOptions pass in NavOptions.restoreState true, any args passed here will be overridden by the restored args.

Parameters
@IdRes int resId	an action id or a destination id to navigate to
Bundle args	arguments to pass to the destination
NavOptions navOptions	special options for this navigation operation

Throws
kotlin.IllegalStateException	if there is no current navigation node
kotlin.IllegalArgumentException	if the desired destination cannot be found from the current destination

navigate

Added in 2.8.0

@MainThread
public final void <T extends Object> navigate(
    @NonNull T route,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a route from an Object in the current NavGraph. If an invalid route is given, an IllegalArgumentException will be thrown.

The target NavDestination must have been created with route from a KClass

If given NavOptions pass in NavOptions.restoreState true, any args passed here as part of the route will be overridden by the restored args.

Parameters
@NonNull T route	route from an Object for the destination
NavOptions navOptions	special options for this navigation operation
Navigator.Extras navigatorExtras	extras to pass to the Navigator

Throws
kotlin.IllegalArgumentException	if the given route is invalid

navigate

Added in 2.4.0

@MainThread
public final void navigate(
    @NonNull String route,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a route in the current NavGraph. If an invalid route is given, an IllegalArgumentException will be thrown.

If given NavOptions pass in NavOptions.restoreState true, any args passed here as part of the route will be overridden by the restored args.

Parameters
@NonNull String route	route for the destination
NavOptions navOptions	special options for this navigation operation
Navigator.Extras navigatorExtras	extras to pass to the Navigator

Throws
kotlin.IllegalArgumentException	if the given route is invalid

navigate

Added in 1.0.0

@MainThread
public void navigate(
    @IdRes int resId,
    Bundle args,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

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

If given NavOptions pass in NavOptions.restoreState true, any args passed here will be overridden by the restored args.

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

Throws
kotlin.IllegalStateException	if navigation graph has not been set for this NavController
kotlin.IllegalArgumentException	if the desired destination cannot be found from the current destination

navigateUp

Added in 1.0.0

@MainThread
public 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.

Returns
boolean	true if navigation was successful, false otherwise

popBackStack

Added in 1.0.0

@MainThread
public 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.

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

popBackStack

Added in 1.0.0

@MainThread
public boolean popBackStack(@IdRes int destinationId, boolean inclusive)

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

Parameters
@IdRes int destinationId	The topmost destination to retain
boolean inclusive	Whether the given destination should also be popped.

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

popBackStack

@MainThread
public final boolean <T extends Object> popBackStack(boolean inclusive, boolean saveState)

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

Parameters
<T extends Object>	The topmost destination to retain with route from a KClass. The target NavDestination must have been created with route from KClass.
boolean inclusive	Whether the given destination should also be popped.
boolean saveState	Whether the back stack and the state of all destinations between the current destination and T should be saved for later restoration via NavOptions.Builder.setRestoreState or the restoreState attribute using the same T (note: this matching ID is true whether inclusive is true or false).

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

popBackStack

Added in 2.4.0

@MainThread
public boolean popBackStack(
    @IdRes int destinationId,
    boolean inclusive,
    boolean saveState
)

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

Parameters
@IdRes int destinationId	The topmost destination to retain
boolean inclusive	Whether the given destination should also be popped.
boolean saveState	Whether the back stack and the state of all destinations between the current destination and the destinationId should be saved for later restoration via NavOptions.Builder.setRestoreState or the restoreState attribute using the same destinationId (note: this matching ID is true whether inclusive is true or false).

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

popBackStack

Added in 2.9.0-alpha04

@MainThread
public final boolean <T extends Object> popBackStack(
    @NonNull KClass<@NonNull T> route,
    boolean inclusive,
    boolean saveState
)

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

Parameters
@NonNull KClass<@NonNull T> route	The topmost destination to retain with route from a KClass. The target NavDestination must have been created with route from KClass.
boolean inclusive	Whether the given destination should also be popped.
boolean saveState	Whether the back stack and the state of all destinations between the current destination and route should be saved for later restoration via NavOptions.Builder.setRestoreState or the restoreState attribute using the same T (note: this matching ID is true whether inclusive is true or false).

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

popBackStack

Added in 2.8.0

@MainThread
public final boolean <T extends Object> popBackStack(
    @NonNull T route,
    boolean inclusive,
    boolean saveState
)

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

Parameters
@NonNull T route	The topmost destination to retain with route from an Object. The target NavDestination must have been created with route from KClass.
boolean inclusive	Whether the given destination should also be popped.
boolean saveState	Whether the back stack and the state of all destinations between the current destination and the route should be saved for later restoration via NavOptions.Builder.setRestoreState or the restoreState attribute using the same route (note: this matching ID is true whether inclusive is true or false).

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

popBackStack

Added in 2.4.0

@MainThread
public final boolean popBackStack(@NonNull String route, boolean inclusive, boolean saveState)

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

Parameters
@NonNull String route	The topmost destination to retain. May contain filled in arguments as long as it is exact match with route used to navigate.
boolean inclusive	Whether the given destination should also be popped.
boolean saveState	Whether the back stack and the state of all destinations between the current destination and the route should be saved for later restoration via NavOptions.Builder.setRestoreState or the restoreState attribute using the same route (note: this matching ID is true whether inclusive is true or false).

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

removeOnDestinationChangedListener

Added in 1.0.0

public void removeOnDestinationChangedListener(
    @NonNull NavController.OnDestinationChangedListener listener
)

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

Parameters
@NonNull NavController.OnDestinationChangedListener listener	the listener to remove

restoreState

Added in 1.0.0

@CallSuper
public void restoreState(Bundle navState)

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
Bundle navState	state bundle to restore

saveState

Added in 1.0.0

@CallSuper
public Bundle saveState()

Saves all navigation controller state to a Bundle.

State may be restored from a bundle returned from this method by calling restoreState. Saving controller state is the responsibility of a NavHost.

Returns
Bundle	saved state for this controller

setGraph

Added in 1.0.0

@MainThread
@CallSuper
public void setGraph(@NonNull NavGraph graph)

The topmost navigation graph associated with this NavController.

When this is set any current navigation graph data (including back stack) will be replaced.

Throws
kotlin.IllegalStateException	if called before setGraph().

See also
setGraph

setGraph

Added in 1.0.0

@MainThread
@CallSuper
public void setGraph(@NavigationRes int graphResId)

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 graph.

Parameters
@NavigationRes int graphResId	resource id of the navigation graph to inflate

See also
navInflater
setGraph
graph

setGraph

Added in 1.0.0

@MainThread
@CallSuper
public void setGraph(@NonNull NavGraph graph, Bundle startDestinationArgs)

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 graph.

Parameters
@NonNull NavGraph graph	graph to set
Bundle startDestinationArgs	arguments to send to the start destination of the graph

See also
setGraph
graph

setGraph

Added in 1.0.0

@MainThread
@CallSuper
public void setGraph(@NavigationRes int graphResId, Bundle startDestinationArgs)

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 graph.

Parameters
@NavigationRes int graphResId	resource id of the navigation graph to inflate
Bundle startDestinationArgs	arguments to send to the start destination of the graph

See also
navInflater
setGraph
graph

Extension functions

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @IdRes int id,
    @IdRes int startDestination,
    @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder
)

This method is deprecated.
Use routes to create your NavGraph instead

Construct a new NavGraph

Parameters
@IdRes int id	the graph's unique id
@IdRes int startDestination	the route for the start destination
@ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder	the builder used to construct the graph

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-dynamic-features-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @IdRes int id,
    @IdRes int startDestination,
    @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder
)

This method is deprecated.
Use routes to create your dynamic NavGraph instead

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

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @NonNull String startDestination,
    String route,
    @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder
)

Construct a new NavGraph

Parameters
@NonNull String startDestination	the route for the start destination
String route	the route for the graph
@ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder	the builder used to construct the graph

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-dynamic-features-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @NonNull String startDestination,
    String route,
    @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder
)

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

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @NonNull Object startDestination,
    KClass<@NonNull ?> route,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,
    @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder
)

Construct a new NavGraph

Parameters
@NonNull Object startDestination	the starting destination's route from an Object for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
KClass<@NonNull ?> route	the graph's unique route from a KClass
@NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap	A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
@ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder	the builder used to construct the graph

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-dynamic-features-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @NonNull Object startDestination,
    KClass<@NonNull ?> route,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,
    @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder
)

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

Parameters
@NonNull Object startDestination	the starting destination's route from an Object for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
KClass<@NonNull ?> route	the graph's unique route from a KClass
@NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap	A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
@ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder	the builder used to construct the graph

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @NonNull KClass<@NonNull ?> startDestination,
    KClass<@NonNull ?> route,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,
    @ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder
)

Construct a new NavGraph

Parameters
@NonNull KClass<@NonNull ?> startDestination	the starting destination's route from a KClass for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
KClass<@NonNull ?> route	the graph's unique route from a KClass
@NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap	A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
@ExtensionFunctionType @NonNull Function1<@NonNull NavGraphBuilder, Unit> builder	the builder used to construct the graph

NavControllerKt.createGraph

Artifact: androidx.navigation:navigation-dynamic-features-runtime

View Source

public final @NonNull NavGraph NavControllerKt.createGraph(
    @NonNull NavController receiver,
    @NonNull KClass<@NonNull ?> startDestination,
    KClass<@NonNull ?> route,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap,
    @ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder
)

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

Parameters
@NonNull KClass<@NonNull ?> startDestination	the starting destination's route from a KClass for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
KClass<@NonNull ?> route	the graph's unique route from a KClass
@NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap	A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
@ExtensionFunctionType @NonNull Function1<@NonNull DynamicNavGraphBuilder, Unit> builder	the builder used to construct the graph

NavControllerKt.navigateUp

Artifact: androidx.navigation:navigation-ui

View Source

public final boolean NavControllerKt.navigateUp(
    @NonNull NavController receiver,
    @NonNull AppBarConfiguration appBarConfiguration
)

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

Returns
boolean	True if the NavController was able to navigate up.

NavControllerKt.navigateUp

Artifact: androidx.navigation:navigation-ui

View Source

public final boolean NavControllerKt.navigateUp(
    @NonNull NavController receiver,
    Openable drawerLayout
)

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

This is equivalent to calling NavController.navigateUp if the Openable layout is null.

Returns
boolean	True if the NavController was able to navigate up.