androidx.navigation | API reference

Added in 2.4.0

fun ActivityNavigatorExtras(
    activityOptions: ActivityOptionsCompat? = null,
    flags: Int = 0
): ActivityNavigator.Extras

Create a new ActivityNavigator.Extras instance with a specific ActivityOptionsCompat instance and/or any Intent.FLAG_ACTIVITY_ flags.

Parameters
`activityOptions: ActivityOptionsCompat? = null`	Optional `ActivityOptionsCompat` to pass through to `androidx.core.app.ActivityCompat.startActivity`.
`flags: Int = 0`	`Intent.FLAG_ACTIVITY_` flags to add to the Intent.

navArgument

Cmn

Added in 2.4.0

fun navArgument(name: String, builder: NavArgumentBuilder.() -> Unit): NamedNavArgument

Construct a new NavArgument

navDeepLink

Cmn

Added in 2.4.0

fun navDeepLink(deepLinkBuilder: NavDeepLinkDslBuilder.() -> Unit): NavDeepLink

Construct a new NavDeepLink

Parameters
`deepLinkBuilder: NavDeepLinkDslBuilder.() -> Unit`	the builder used to construct the deeplink

navDeepLink

Cmn

inline fun <T : Any> navDeepLink(
    basePath: String,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    noinline deepLinkBuilder: NavDeepLinkDslBuilder.() -> Unit = {}
): NavDeepLink

Construct a new NavDeepLink

Extracts deeplink arguments from T and appends it to the basePath. The base path & generated arguments form the final uri pattern for the deeplink.

See docs on the safe args version of NavDeepLink.Builder.setUriPattern for the final uriPattern's generation logic.

Parameters
`<T : Any>`	The deepLink KClass to extract arguments from
`basePath: String`	The base uri path to append arguments onto
`typeMap: Map<KType, NavType<*>> = emptyMap()`	map of destination arguments' kotlin type `KType` to its respective custom `NavType`. May be empty if `T` does not use custom NavTypes.
`noinline deepLinkBuilder: NavDeepLinkDslBuilder.() -> Unit = {}`	the builder used to construct the deeplink

navDeepLink

Cmn

Added in 2.9.0-alpha07

fun <T : Any> navDeepLink(
    route: KClass<T>,
    basePath: String,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    deepLinkBuilder: NavDeepLinkDslBuilder.() -> Unit
): NavDeepLink

Construct a new NavDeepLink

Extracts deeplink arguments from T and appends it to the basePath. The base path & generated arguments form the final uri pattern for the deeplink.

See docs on the safe args version of NavDeepLink.Builder.setUriPattern for the final uriPattern's generation logic.

Parameters
`route: KClass<T>`	The deepLink `KClass` to extract arguments from
`basePath: String`	The base uri path to append arguments onto
`typeMap: Map<KType, NavType<*>> = emptyMap()`	map of destination arguments' kotlin type `KType` to its respective custom `NavType`. May be empty if `route` does not use custom NavTypes.
`deepLinkBuilder: NavDeepLinkDslBuilder.() -> Unit`	the builder used to construct the deeplink

navOptions

Cmn

Added in 2.4.0

fun navOptions(optionsBuilder: NavOptionsBuilder.() -> Unit): NavOptions

Construct a new NavOptions

Extension functions

android

Added in 2.4.0

Deprecated in 2.4.0

inline fun NavGraphBuilder.activity(id: @IdRes Int, builder: ActivityNavigatorDestinationBuilder.() -> Unit): Unit

Construct a new ActivityNavigator.Destination

android

Added in 2.4.0

inline fun NavGraphBuilder.activity(route: String, builder: ActivityNavigatorDestinationBuilder.() -> Unit): Unit

Construct a new ActivityNavigator.Destination

android

inline fun <T : Any> NavGraphBuilder.activity(
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: ActivityNavigatorDestinationBuilder.() -> Unit
): Unit

Construct a new ActivityNavigator.Destination

Parameters
`<T : Any>`	destination's unique route from a `KClass`
`typeMap: Map<KType, NavType<*>> = emptyMap()`	map of destination arguments' kotlin type `KType` to its respective custom `NavType`. May be empty if `T` does not use custom NavTypes.
`builder: ActivityNavigatorDestinationBuilder.() -> Unit`	the builder used to construct the fragment destination

android

Added in 2.4.0

operator fun NavGraph.contains(id: @IdRes Int): Boolean

Returns true if a destination with id is found in this navigation graph.

Cmn

inline operator fun <T : Any> NavGraph.contains(route: KClass<T>): Boolean

Returns true if a destination with route is found in this navigation graph.

Cmn

Added in 2.4.0

operator fun NavGraph.contains(route: String): Boolean

Returns true if a destination with route is found in this navigation graph.

Cmn

Added in 2.8.0

operator fun <T : Any> NavGraph.contains(route: T): Boolean

Returns true if a destination with route is found in this navigation graph.

android

Added in 2.4.0

Deprecated in 2.4.0

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

android

Added in 2.4.0

Deprecated in 2.4.0

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

Construct a new NavGraph

Cmn

Added in 2.4.0

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

Cmn

Added in 2.4.0

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

Construct a new NavGraph

Cmn

Added in 2.8.0

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

Cmn

Added in 2.8.0

inline fun NavHost.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

Cmn

Added in 2.8.0

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

Cmn

Added in 2.8.0

inline fun NavHost.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

findNavController

android

Added in 2.4.0

fun View.findNavController(): NavController

Find a NavController associated with a View.

Calling this on a View not within a NavHost will result in an IllegalStateException

findNavController

android

Added in 2.4.0

fun Activity.findNavController(viewId: @IdRes Int): NavController

Find a NavController given the id of a View and its containing Activity.

Calling this on a View that is not a NavHost or within a NavHost will result in an IllegalStateException

Cmn android

Added in 2.4.0

inline operator fun <T : Navigator<NavDestination>> NavigatorProvider.get(clazz: KClass<T>): T

Retrieves a registered Navigator using the name provided by the Navigator.Name.

Throws
`kotlin.IllegalStateException`	if the Navigator has not been added

android

Added in 2.4.0

inline operator fun NavGraph.get(id: @IdRes Int): NavDestination

Returns the destination with id.

Throws
`kotlin.IllegalArgumentException`	if no destination is found with that id.

Cmn

Added in 2.4.0

inline operator fun <T : Navigator<NavDestination>> NavigatorProvider.get(name: String): T

Retrieves a registered Navigator by name.

Throws
`kotlin.IllegalStateException`	if the Navigator has not been added

Cmn

inline operator fun <T : Any> NavGraph.get(route: KClass<T>): NavDestination

Returns the destination with route from KClass.

Throws
`kotlin.IllegalArgumentException`	if no destination is found with that route.

Cmn

Added in 2.4.0

inline operator fun NavGraph.get(route: String): NavDestination

Returns the destination with route.

Throws
`kotlin.IllegalArgumentException`	if no destination is found with that route.

Cmn

Added in 2.8.0

inline operator fun <T : Any> NavGraph.get(route: T): NavDestination

Returns the destination with route from an Object.

Throws
`kotlin.IllegalArgumentException`	if no destination is found with that route.

Cmn

Added in 2.4.0

inline operator fun NavGraph.minusAssign(node: NavDestination): Unit

Removes node from this navigation graph.

navArgs

android

@MainThread
inline fun <Args : NavArgs> Activity.navArgs(): NavArgsLazy<Args>

Returns a Lazy delegate to access the Activity's extras as an Args instance.

It is strongly recommended that this method only be used when the Activity is started by androidx.navigation.NavController.navigate with the corresponding androidx.navigation.NavDirections object, which ensures that the required arguments are present.

class MyActivity : Activity() {
    val args: MyActivityArgs by navArgs()
}

This property can be accessed only after the Activity is attached to the Application, and access prior to that will result in IllegalStateException.

navGraphViewModels

android

Artifact: androidx.navigation:navigation-fragment

@MainThread
inline fun <VM : ViewModel> Fragment.navGraphViewModels(
    navGraphId: @IdRes Int,
    noinline extrasProducer: (() -> CreationExtras)? = null,
    noinline factoryProducer: (() -> ViewModelProvider.Factory)? = null
): Lazy<VM>

Returns a property delegate to access a ViewModel scoped to a navigation graph present on the NavController back stack:

class MyFragment : Fragment() {
    val viewmodel: MainViewModel by navGraphViewModels(R.id.main)
}

Custom ViewModelProvider.Factory can be defined via factoryProducer parameter, factory returned by it will be used to create ViewModel:

class MyFragment : Fragment() {
    val viewmodel: MainViewModel by navGraphViewModels(R.id.main) { myFactory }
}

This property can be accessed only after this NavGraph is on the NavController back stack, and an attempt access prior to that will result in an IllegalArgumentException.

Parameters
`navGraphId: @IdRes Int`	ID of a NavGraph that exists on the `NavController` back stack
`noinline extrasProducer: (() -> CreationExtras)? = null`	lambda that will be called during initialization to return `CreationExtras`. If none is provided, this will use the extras from the `NavBackStackEntry` referenced by the `navGraphId`.
`noinline factoryProducer: (() -> ViewModelProvider.Factory)? = null`	lambda that will be called during initialization to return `ViewModelProvider.Factory`. If none is provided, this will use the factory from the `NavBackStackEntry` referenced by the `navGraphId`.

navGraphViewModels

android

Artifact: androidx.navigation:navigation-fragment

@MainThread
inline fun <VM : ViewModel> Fragment.navGraphViewModels(
    navGraphRoute: String,
    noinline extrasProducer: (() -> CreationExtras)? = null,
    noinline factoryProducer: (() -> ViewModelProvider.Factory)? = null
): Lazy<VM>

Returns a property delegate to access a ViewModel scoped to a navigation graph present on the NavController back stack:

class MyFragment : Fragment() {
    val viewModel: MainViewModel by navGraphViewModels("main")
}

Custom ViewModelProvider.Factory can be defined via factoryProducer parameter, factory returned by it will be used to create ViewModel:

class MyFragment : Fragment() {
    val viewModel: MainViewModel by navGraphViewModels("main") { myFactory }
}

This property can be accessed only after this NavGraph is on the NavController back stack, and an attempt access prior to that will result in an IllegalArgumentException.

Parameters
`navGraphRoute: String`	`NavDestination.route` of a NavGraph that exists on the `NavController` back stack. If a `NavDestination` with the given route does not exist on the back stack, an `IllegalArgumentException` will be thrown.
`noinline extrasProducer: (() -> CreationExtras)? = null`	lambda that will be called during initialization to return `CreationExtras`. If none is provided, this will use the extras from the `NavBackStackEntry` referenced by the `navGraphRoute`.
`noinline factoryProducer: (() -> ViewModelProvider.Factory)? = null`	lambda that will be called during initialization to return `ViewModelProvider.Factory`. If none is provided, this will use the factory from the `NavBackStackEntry` referenced by the `navGraphRoute`.

android

Added in 2.4.0

Deprecated in 2.4.0

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

Construct a new NavGraph

Parameters
`id: @IdRes Int = 0`	the destination's unique id
`startDestination: @IdRes Int`	the starting destination for this NavGraph
`builder: NavGraphBuilder.() -> Unit`	the builder used to construct the graph

Returns
`NavGraph`	the newly constructed NavGraph

android

Added in 2.4.0

Deprecated in 2.4.0

inline fun NavGraphBuilder.navigation(
    id: @IdRes Int,
    startDestination: @IdRes Int,
    builder: NavGraphBuilder.() -> Unit
): Unit

Construct a nested NavGraph

Parameters
`id: @IdRes Int`	the destination's unique id
`startDestination: @IdRes Int`	the starting destination for this NavGraph
`builder: NavGraphBuilder.() -> Unit`	the builder used to construct the graph

Returns
`Unit`	the newly constructed nested NavGraph

Cmn

inline fun <T : Any> NavGraphBuilder.navigation(
    startDestination: Any,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    noinline builder: NavGraphBuilder.() -> Unit
): Unit

Construct a nested NavGraph

Parameters
`<T : Any>`	the graph's unique route from a KClass
`startDestination: Any`	the starting destination's route from an Object for this NavGraph. The respective NavDestination must be added with route from a `KClass` in order to match.
`typeMap: Map<KType, NavType<*>> = emptyMap()`	A mapping of KType to custom NavType<*> in the `T`. May be empty if `T` does not use custom NavTypes.
`noinline builder: NavGraphBuilder.() -> Unit`	the builder used to construct the graph

Returns
`Unit`	the newly constructed nested NavGraph

Cmn

inline fun <T : Any> NavGraphBuilder.navigation(
    startDestination: KClass<*>,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    noinline builder: NavGraphBuilder.() -> Unit
): Unit

Construct a nested NavGraph

Parameters
`<T : Any>`	the graph's unique route from a KClass
`startDestination: KClass<*>`	the starting destination's route from a `KClass` for this NavGraph. The respective NavDestination must be added with route from a `KClass` in order to match.
`typeMap: Map<KType, NavType<*>> = emptyMap()`	A mapping of KType to custom NavType<*> in the `T`. May be empty if `T` does not use custom NavTypes.
`noinline builder: NavGraphBuilder.() -> Unit`	the builder used to construct the graph

Returns
`Unit`	the newly constructed nested NavGraph

Cmn

Added in 2.4.0

inline fun NavigatorProvider.navigation(
    startDestination: String,
    route: String? = null,
    builder: NavGraphBuilder.() -> Unit
): NavGraph

Construct a new NavGraph

Parameters
`startDestination: String`	the starting destination's route for this NavGraph
`route: String? = null`	the destination's unique route
`builder: NavGraphBuilder.() -> Unit`	the builder used to construct the graph

Returns
`NavGraph`	the newly constructed NavGraph

Cmn

Added in 2.4.0

inline fun NavGraphBuilder.navigation(
    startDestination: String,
    route: String,
    builder: NavGraphBuilder.() -> Unit
): Unit

Construct a nested NavGraph

Parameters
`startDestination: String`	the starting destination's route for this NavGraph
`route: String`	the destination's unique route
`builder: NavGraphBuilder.() -> Unit`	the builder used to construct the graph

Returns
`Unit`	the newly constructed nested NavGraph

Cmn

Added in 2.9.0-alpha07

fun <T : Any> NavGraphBuilder.navigation(
    route: KClass<T>,
    startDestination: Any,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: NavGraphBuilder.() -> Unit
): Unit

Construct a nested NavGraph

Parameters
`route: KClass<T>`	the graph's unique route from a KClass
`startDestination: Any`	the starting destination's route from an Object for this NavGraph. The respective NavDestination must be added with route from a `KClass` in order to match.
`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

Returns
`Unit`	the newly constructed nested NavGraph

Cmn

Added in 2.9.0-alpha07

fun <T : Any> NavGraphBuilder.navigation(
    route: KClass<T>,
    startDestination: KClass<*>,
    typeMap: Map<KType, NavType<*>> = emptyMap(),
    builder: NavGraphBuilder.() -> Unit
): Unit

Construct a nested NavGraph

Parameters
`route: KClass<T>`	the graph's unique route from KClass
`startDestination: KClass<*>`	the starting destination's route from a `KClass` for this NavGraph. The respective NavDestination must be added with route from a `KClass` in order to match.
`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

Returns
`Unit`	the newly constructed nested NavGraph

Cmn

Added in 2.8.0

inline fun NavigatorProvider.navigation(
    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 with route from a `KClass` in order to match.
`route: KClass<*>? = null`	the graph's unique route as 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

Returns
`NavGraph`	the newly constructed NavGraph

Cmn

Added in 2.8.0

inline fun NavigatorProvider.navigation(
    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 with route from a `KClass` in order to match.
`route: KClass<*>? = null`	the graph's unique route as 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

Returns
`NavGraph`	the newly constructed NavGraph

Cmn

Added in 2.4.0

inline operator fun NavigatorProvider.plusAssign(navigator: Navigator<NavDestination>): Unit

Cmn

Added in 2.4.0

inline operator fun NavGraph.plusAssign(node: NavDestination): Unit

Adds a destination to this NavGraph. The destination must have an NavDestination.id set.

The destination must not have a parent set. If the destination is already part of a NavGraph, call NavGraph.remove before calling this method.

Parameters
`node: NavDestination`	destination to add

Cmn

Added in 2.4.0

inline operator fun NavGraph.plusAssign(other: NavGraph): Unit

Add all destinations from another collection to this one. As each destination has at most one parent, the destinations will be removed from the given NavGraph.

Parameters
`other: NavGraph`	collection of destinations to add. All destinations will be removed from the parameter graph after being added to this graph.

Cmn

Added in 2.4.0

inline operator fun NavigatorProvider.set(
    name: String,
    navigator: Navigator<NavDestination>
): Navigator<NavDestination>?

Returns
`Navigator<NavDestination>?`	the previously added `Navigator` for the given name, if any

Cmn

inline fun <T : Any?> NavBackStackEntry.toRoute(): T

Returns route as an object of type T

Extrapolates arguments from NavBackStackEntry.arguments and recreates object T

Parameters
`<T : Any?>`	the entry's `NavDestination.route` as a `KClass`

Returns
`T`	A new instance of this entry's `NavDestination.route` as an object of type `T`

Cmn

Added in 2.9.0-alpha07

fun <T : Any?> NavBackStackEntry.toRoute(route: KClass<*>): T

Returns route as an object of type T

Extrapolates arguments from NavBackStackEntry.arguments and recreates object T

Parameters
`route: KClass<*>`	the entry's `NavDestination.route` as a `KClass`

Returns
`T`	A new instance of this entry's `NavDestination.route` as an object of type `T`

toRoute

Cmn

inline fun <T : Any> SavedStateHandle.toRoute(
    typeMap: Map<KType, NavType<*>> = emptyMap()
): T

Returns route as an object of type T

Extrapolates arguments from SavedStateHandle and recreates object T

Parameters
`<T : Any>`	the entry's `NavDestination.route` as a `KClass`
`typeMap: Map<KType, NavType<*>> = emptyMap()`	A mapping of KType to custom NavType<*> in `T`. May be empty if `T` does not use custom NavTypes.

Returns
`T`	A new instance of this entry's `NavDestination.route` as an object of type `T`

toRoute

Cmn