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 navInflater 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

OnDestinationChangedListener receives a callback when the currentDestination or its arguments change.

Public companion functions
Unit

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).
Cmn
android

Public constructors
android

Public functions
open Unit

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

Clears any saved state associated with KClass T that was previously saved via popBackStack when using a saveState value of true.
Cmn
android
Boolean
@MainThread
<T : Any> clearBackStack(route: KClass<T>)

Clears any saved state associated with KClass route that was previously saved via popBackStack when using a saveState value of true.
Cmn
android
Boolean
@MainThread
<T : Any> clearBackStack(route: T)

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

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

Gets the topmost NavBackStackEntry for a route from KClass.
Cmn
android
NavBackStackEntry
<T : Any> getBackStackEntry(route: KClass<T>)

Gets the topmost NavBackStackEntry for a route from KClass.
Cmn
android
NavBackStackEntry
<T : Any> getBackStackEntry(route: T)

Gets the topmost NavBackStackEntry for a route from an Object.
Cmn
android
NavBackStackEntry

Gets the topmost NavBackStackEntry for a route.
Cmn
android
Boolean

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

Navigate to a destination via the given deep link Uri.
Cmn
android
open Unit

Navigate to a destination via the given NavDeepLinkRequest.
Cmn
android
open Unit
@MainThread
navigate(deepLink: NavUri, navOptions: NavOptions?)

Navigate to a destination via the given deep link Uri.
Cmn
android
open Unit

Navigate to a destination via the given NavDeepLinkRequest.
Cmn
android
Unit
@MainThread
<T : Any> navigate(route: T, builder: NavOptionsBuilder.() -> Unit)

Navigate to a route from an Object in the current NavGraph.
Cmn
android
Unit
@MainThread
navigate(route: String, builder: NavOptionsBuilder.() -> Unit)

Navigate to a route in the current NavGraph.
Cmn
android
open Unit
@MainThread
navigate(
    deepLink: NavUri,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination via the given deep link Uri.
Cmn
android
open Unit
@MainThread
navigate(
    request: NavDeepLinkRequest,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination via the given NavDeepLinkRequest.
Cmn
android
Unit
@MainThread
<T : Any> navigate(
    route: T,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a route from an Object in the current NavGraph.
Cmn
android
Unit
@MainThread
navigate(
    route: String,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a route in the current NavGraph.
Cmn
android
open Boolean

Attempts to navigate up in the navigation hierarchy.
Cmn
android
open Boolean

Attempts to pop the controller's back stack.
Cmn
android
inline Boolean
@MainThread
<T : Any> popBackStack(inclusive: Boolean, saveState: Boolean)

Attempts to pop the controller's back stack back to a specific destination.
Cmn
android
Boolean
@MainThread
<T : Any> popBackStack(
    route: KClass<T>,
    inclusive: Boolean,
    saveState: Boolean
)

Attempts to pop the controller's back stack back to a specific destination.
Cmn
android
Boolean
@MainThread
<T : Any> popBackStack(route: T, inclusive: Boolean, saveState: Boolean)

Attempts to pop the controller's back stack back to a specific destination.
Cmn
android
Boolean
@MainThread
popBackStack(route: String, inclusive: Boolean, saveState: Boolean)

Attempts to pop the controller's back stack back to a specific destination.
Cmn
android
open Unit

Removes an OnDestinationChangedListener from this controller.
Cmn
android
open Unit

Restores all navigation controller state from a SavedState.
Cmn
android
open SavedState?

Saves all navigation controller state to a SavedState.
Cmn
android
open Unit
@MainThread
@CallSuper
setGraph(graph: NavGraph, startDestinationArgs: SavedState?)

Sets the navigation graph to the specified graph.
Cmn
android

Public properties
open NavBackStackEntry?

The topmost NavBackStackEntry.
Cmn
android
Flow<NavBackStackEntry>

A Flow that will emit the currently active NavBackStackEntry whenever it changes.
Cmn
android
open NavDestination?

The current destination.
Cmn
android
open NavGraph

The topmost navigation graph associated with this NavController.
Cmn
android
open NavigatorProvider

The NavController's NavigatorProvider.
Cmn
android
open NavBackStackEntry?

The previous visible NavBackStackEntry.
Cmn
android
StateFlow<List<NavBackStackEntry>>

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

Extension functions
inline NavGraph
NavController.createGraph(
    id: @IdRes Int,
    startDestination: @IdRes Int,
    builder: NavGraphBuilder.() -> Unit
)

This function is deprecated. Use routes to create your NavGraph instead
android
inline NavGraph
NavController.createGraph(
    id: @IdRes Int,
    startDestination: @IdRes Int,
    builder: DynamicNavGraphBuilder.() -> Unit
)

This function is deprecated. Use routes to create your dynamic NavGraph instead
android
inline NavGraph
NavController.createGraph(
    startDestination: String,
    route: String?,
    builder: NavGraphBuilder.() -> Unit
)

Construct a new NavGraph
Cmn
inline NavGraph
NavController.createGraph(
    startDestination: String,
    route: String?,
    builder: DynamicNavGraphBuilder.() -> Unit
)

Construct a new androidx.navigation.NavGraph that supports dynamic navigation destinations
android
inline NavGraph
NavController.createGraph(
    startDestination: Any,
    route: KClass<*>?,
    typeMap: Map<KType, NavType<*>>,
    builder: NavGraphBuilder.() -> Unit
)

Construct a new NavGraph
Cmn
inline NavGraph
NavController.createGraph(
    startDestination: Any,
    route: KClass<*>?,
    typeMap: Map<KType, NavType<*>>,
    builder: DynamicNavGraphBuilder.() -> Unit
)

Construct a new androidx.navigation.NavGraph that supports dynamic navigation destinations
android
inline NavGraph
NavController.createGraph(
    startDestination: KClass<*>,
    route: KClass<*>?,
    typeMap: Map<KType, NavType<*>>,
    builder: NavGraphBuilder.() -> Unit
)

Construct a new NavGraph
Cmn
inline NavGraph
NavController.createGraph(
    startDestination: KClass<*>,
    route: KClass<*>?,
    typeMap: Map<KType, NavType<*>>,
    builder: DynamicNavGraphBuilder.() -> Unit
)

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

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

Handles the Up button by delegating its behavior to the given NavController.
android
State<NavBackStackEntry?>

Gets the current navigation back stack entry as a MutableState.
Cmn
State<NavBackStackEntry?>

Gets the current navigation back stack entry as a State.
android

Public companion functions

enableDeepLinkSaveState

Cmn android
Added in 2.4.0
@NavDeepLinkSaveStateControl
fun enableDeepLinkSaveState(saveState: Boolean): Unit

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.

Public constructors

android 
NavController()

Public functions

addOnDestinationChangedListener

Cmn android
Added in 1.0.0
open fun addOnDestinationChangedListener(
    listener: NavController.OnDestinationChangedListener
): Unit

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
listener: NavController.OnDestinationChangedListener

the listener to receive events

clearBackStack

Cmn android 
@MainThread
inline fun <T : Any> clearBackStack(): Boolean

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

Parameters
<T : Any>

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

Cmn android
Added in 2.9.0-alpha07
@MainThread
fun <T : Any> clearBackStack(route: KClass<T>): Boolean

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

Parameters
route: KClass<T>

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

Cmn android
Added in 2.8.0
@MainThread
fun <T : Any> clearBackStack(route: T): Boolean

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

Parameters
route: T

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

Cmn android
Added in 2.4.0
@MainThread
fun clearBackStack(route: String): Boolean

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

Parameters
route: String

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.

getBackStackEntry

Cmn android 
inline fun <T : Any> getBackStackEntry(): NavBackStackEntry

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 : Any>

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

Cmn android
Added in 2.9.0-alpha07
fun <T : Any> getBackStackEntry(route: KClass<T>): NavBackStackEntry

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
route: KClass<T>

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

Cmn android
Added in 2.8.0
fun <T : Any> getBackStackEntry(route: T): NavBackStackEntry

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
route: T

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

Cmn android
Added in 2.4.0
fun getBackStackEntry(route: String): NavBackStackEntry

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
route: String

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

handleDeepLink

Cmn android
Added in 2.9.0-alpha07
@MainThread
fun handleDeepLink(request: NavDeepLinkRequest): Boolean

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
request: NavDeepLinkRequest

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
Cmn android 
@MainThread
open fun navigate(deepLink: NavUri): Unit

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
deepLink: NavUri

deepLink to the destination reachable from the current NavGraph
See also
navigate
Cmn android
Added in 2.3.0
@MainThread
open fun navigate(request: NavDeepLinkRequest): Unit

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
request: NavDeepLinkRequest

deepLinkRequest to the destination reachable from the current NavGraph
Throws
kotlin.IllegalArgumentException

if the given deep link request is invalid
Cmn android 
@MainThread
open fun navigate(deepLink: NavUri, navOptions: NavOptions?): Unit

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
deepLink: NavUri

deepLink to the destination reachable from the current NavGraph
navOptions: NavOptions?

special options for this navigation operation
See also
navigate
Cmn android
Added in 2.3.0
@MainThread
open fun navigate(request: NavDeepLinkRequest, navOptions: NavOptions?): Unit

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
request: NavDeepLinkRequest

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
Cmn android
Added in 2.8.0
@MainThread
fun <T : Any> navigate(route: T, builder: NavOptionsBuilder.() -> Unit): Unit

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
route: T

route from an Object for the destination
builder: NavOptionsBuilder.() -> Unit

DSL for constructing a new NavOptions
Throws
kotlin.IllegalArgumentException

if the given route is invalid
Cmn android
Added in 2.4.0
@MainThread
fun navigate(route: String, builder: NavOptionsBuilder.() -> Unit): Unit

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
route: String

route for the destination
builder: NavOptionsBuilder.() -> Unit

DSL for constructing a new NavOptions
Throws
kotlin.IllegalArgumentException

if the given route is invalid
Cmn android 
@MainThread
open fun navigate(
    deepLink: NavUri,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
): Unit

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
deepLink: NavUri

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
Cmn android
Added in 2.3.0
@MainThread
open fun navigate(
    request: NavDeepLinkRequest,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
): Unit

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
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
Throws
kotlin.IllegalArgumentException

if the given deep link request is invalid
Cmn android
Added in 2.8.0
@MainThread
fun <T : Any> navigate(
    route: T,
    navOptions: NavOptions? = null,
    navigatorExtras: Navigator.Extras? = null
): Unit

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
route: T

route from an Object for the destination
navOptions: NavOptions? = null

special options for this navigation operation
navigatorExtras: Navigator.Extras? = null

extras to pass to the Navigator
Throws
kotlin.IllegalArgumentException

if the given route is invalid
Cmn android
Added in 2.4.0
@MainThread
fun navigate(
    route: String,
    navOptions: NavOptions? = null,
    navigatorExtras: Navigator.Extras? = null
): Unit

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
route: String

route for the destination
navOptions: NavOptions? = null

special options for this navigation operation
navigatorExtras: Navigator.Extras? = null

extras to pass to the Navigator
Throws
kotlin.IllegalArgumentException

if the given route is invalid
Cmn android
Added in 1.0.0
@MainThread
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 Activity.finish 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

Cmn android
Added in 1.0.0
@MainThread
open fun popBackStack(): Boolean

Attempts to pop the controller's back stack. Analogous to when the user presses the system android.view.KeyEvent.KEYCODE_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

Cmn android 
@MainThread
inline fun <T : Any> popBackStack(inclusive: Boolean, saveState: Boolean = false): Boolean

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

Parameters
<T : Any>

The topmost destination to retain with route from a KClass. The target NavDestination must have been created with route from KClass.
inclusive: Boolean

Whether the given destination should also be popped.
saveState: Boolean = false

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

Cmn android
Added in 2.9.0-alpha07
@MainThread
fun <T : Any> popBackStack(
    route: KClass<T>,
    inclusive: Boolean,
    saveState: Boolean = false
): Boolean

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

Parameters
route: KClass<T>

The topmost destination to retain with route from a KClass. The target NavDestination must have been created with route from KClass.
inclusive: Boolean

Whether the given destination should also be popped.
saveState: Boolean = false

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

Cmn android
Added in 2.8.0
@MainThread
fun <T : Any> popBackStack(route: T, inclusive: Boolean, saveState: Boolean = false): Boolean

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

Parameters
route: T

The topmost destination to retain with route from an Object. The target NavDestination must have been created with route from KClass.
inclusive: Boolean

Whether the given destination should also be popped.
saveState: Boolean = false

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

Cmn android
Added in 2.4.0
@MainThread
fun popBackStack(route: String, inclusive: Boolean, saveState: Boolean = false): Boolean

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

Parameters
route: String

The topmost destination to retain. May contain filled in arguments as long as it is exact match with route used to navigate.
inclusive: Boolean

Whether the given destination should also be popped.
saveState: Boolean = false

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

Cmn android
Added in 1.0.0
open fun removeOnDestinationChangedListener(
    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

Cmn android 
@CallSuper
open fun restoreState(navState: SavedState?): Unit

Restores all navigation controller state from a SavedState. This should be called before any call to setGraph.

State may be saved to a SavedState by calling saveState. Restoring controller state is the responsibility of a NavHost.

Parameters
navState: SavedState?

SavedState to restore

saveState

Cmn android
Added in 1.0.0
@CallSuper
open fun saveState(): SavedState?

Saves all navigation controller state to a SavedState.

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

Returns
SavedState?

saved state for this controller

setGraph

Cmn android 
@MainThread
@CallSuper
open fun setGraph(graph: NavGraph, startDestinationArgs: SavedState?): 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 graph.

Parameters
graph: NavGraph

graph to set
startDestinationArgs: SavedState?

arguments to send to the start destination of the graph
See also
setGraph
graph

Public properties

currentBackStackEntry

Cmn android
Added in 2.3.0
open val currentBackStackEntry: NavBackStackEntry?

The topmost NavBackStackEntry.

Returns
NavBackStackEntry?

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

currentBackStackEntryFlow

Cmn android
Added in 2.4.0
val currentBackStackEntryFlow: Flow<NavBackStackEntry>

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

currentDestination

Cmn android
Added in 1.0.0
open val currentDestination: NavDestination?

The current destination.

graph

Cmn android
Added in 1.0.0
open var graph: NavGraph

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
Cmn android
Added in 1.0.0
open val navigatorProvider: NavigatorProvider

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

previousBackStackEntry

Cmn android
Added in 2.3.0
open val previousBackStackEntry: NavBackStackEntry?

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

visibleEntries

Cmn android
Added in 2.4.0
val visibleEntries: StateFlow<List<NavBackStackEntry>>

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.

Extension functions

createGraph

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

Construct a new NavGraph

Parameters
id: @IdRes Int = 0

the graph's unique id
startDestination: @IdRes Int

the route for the start destination
builder: NavGraphBuilder.() -> Unit

the builder used to construct the graph

createGraph

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

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

createGraph

Cmn 
inline fun NavController.createGraph(
    startDestination: String,
    route: String? = null,
    builder: NavGraphBuilder.() -> Unit
): NavGraph

Construct a new NavGraph

Parameters
startDestination: String

the route for the start destination
route: String? = null

the route for the graph
builder: NavGraphBuilder.() -> Unit

the builder used to construct the graph

createGraph

android 
inline fun NavController.createGraph(
    startDestination: String,
    route: String? = null,
    builder: DynamicNavGraphBuilder.() -> Unit
): NavGraph

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

createGraph

Cmn 
inline fun NavController.createGraph(
    startDestination: Any,
    route: KClass<*>? = null,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: NavGraphBuilder.() -> Unit
): NavGraph

Construct a new NavGraph

Parameters
startDestination: Any

the starting destination's route from an Object for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
route: KClass<*>? = null

the graph's unique route from a KClass
typeMap: Map<KType, NavType<*>> = emptyMap()

A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
builder: NavGraphBuilder.() -> Unit

the builder used to construct the graph

createGraph

android 
inline fun NavController.createGraph(
    startDestination: Any,
    route: KClass<*>? = null,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: DynamicNavGraphBuilder.() -> Unit
): NavGraph

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

Parameters
startDestination: Any

the starting destination's route from an Object for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
route: KClass<*>? = null

the graph's unique route from a KClass
typeMap: Map<KType, NavType<*>> = emptyMap()

A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
builder: DynamicNavGraphBuilder.() -> Unit

the builder used to construct the graph

createGraph

Cmn 
inline fun NavController.createGraph(
    startDestination: KClass<*>,
    route: KClass<*>? = null,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: NavGraphBuilder.() -> Unit
): NavGraph

Construct a new NavGraph

Parameters
startDestination: KClass<*>

the starting destination's route from a KClass for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
route: KClass<*>? = null

the graph's unique route from a KClass
typeMap: Map<KType, NavType<*>> = emptyMap()

A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
builder: NavGraphBuilder.() -> Unit

the builder used to construct the graph

createGraph

android 
inline fun NavController.createGraph(
    startDestination: KClass<*>,
    route: KClass<*>? = null,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: DynamicNavGraphBuilder.() -> Unit
): NavGraph

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

Parameters
startDestination: KClass<*>

the starting destination's route from a KClass for this NavGraph. The respective NavDestination must be added as a KClass in order to match.
route: KClass<*>? = null

the graph's unique route from a KClass
typeMap: Map<KType, NavType<*>> = emptyMap()

A mapping of KType to custom NavType<*> in the route. May be empty if route does not use custom NavTypes.
builder: DynamicNavGraphBuilder.() -> Unit

the builder used to construct the graph

navigateUp

android 
fun NavController.navigateUp(appBarConfiguration: AppBarConfiguration): Boolean

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

Returns
Boolean

True if the NavController was able to navigate up.

navigateUp

android 
fun NavController.navigateUp(drawerLayout: Openable?): Boolean

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.

currentBackStackEntryAsState

Cmn 
@Composable
fun NavController.currentBackStackEntryAsState(): State<NavBackStackEntry?>

Gets the current navigation back stack entry as a MutableState. When the given navController changes the back stack due to a NavController.navigate or NavController.popBackStack this will trigger a recompose and return the top entry on the back stack.

Returns
State<NavBackStackEntry?>

a mutable state of the current back stack entry

currentBackStackEntryAsState

android 
@Composable
fun NavController.currentBackStackEntryAsState(): State<NavBackStackEntry?>

Gets the current navigation back stack entry as a State. When the given navController changes the back stack due to a NavController.navigate or NavController.popBackStack this will trigger a recompose and return the top entry on the back stack.

Returns
State<NavBackStackEntry?>

state of the current back stack entry