NavDestination
Known direct subclasses
ActivityNavigator.Destination

NavDestination for activity navigation
BottomSheetNavigator.Destination

NavDestination specific to BottomSheetNavigator.
ComposeNavigator.Destination

NavDestination specific to ComposeNavigator
DialogFragmentNavigator.Destination

NavDestination specific to DialogFragmentNavigator.
DialogNavigator.Destination

NavDestination specific to DialogNavigator
DynamicIncludeGraphNavigator.DynamicIncludeNavGraph

The graph for dynamic-include.
FragmentNavigator.Destination

NavDestination specific to FragmentNavigator
NavGraph

NavGraph is a collection of NavDestination nodes fetchable by ID.
WearNavigator.Destination

NavDestination specific to WearNavigator
Known indirect subclasses
DynamicFragmentNavigator.Destination

Destination for dynamic feature navigator.
DynamicGraphNavigator.DynamicNavGraph

The NavGraph for dynamic features.

NavDestination represents one node within an overall navigation graph.

Each destination is associated with a Navigator which knows how to navigate to this particular destination.

Destinations declare a set of putAction that they support. These actions form a navigation API for the destination; the same actions declared on different destinations that fill similar roles allow application code to navigate based on semantic intent.

Each destination has a set of arguments that will be applied when navigating to that destination. Any default values for those arguments can be overridden at the time of navigation.

NavDestinations should be created via Navigator.createDestination.

Summary

Nested types
@Retention(value = AnnotationRetention.BINARY)
@Target(allowedTargets = [AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CLASS])
annotation NavDestination.ClassType

This optional annotation allows tooling to offer auto-complete for the android:name attribute.

Public companion functions
inline Boolean

Checks if the NavDestination's route was generated from T
Cmn
android
Boolean
<T : Any> NavDestination.hasRoute(route: KClass<T>)

Checks if the NavDestination's route was generated from T
Cmn
android

Protected companion functions
Class<C?>
<C : Any?> parseClassFromName(
    context: Context,
    name: String,
    expectedClassType: Class<C?>
)

Parse the class associated with this destination from a raw name, generally extracted from the android:name attribute added to the destination's XML.
android

Public companion properties
Sequence<NavDestination>

Provides a sequence of the NavDestination's hierarchy.
Cmn
android

Public constructors
NavDestination(navigatorName: String)
Cmn
android

NavDestinations should be created via Navigator.createDestination.
Cmn
android

Public functions
Unit
addArgument(argumentName: String, argument: NavArgument)

Sets an argument type for an argument name
Cmn
android
Unit
addDeepLink(navDeepLink: NavDeepLink)

Add a deep link to this destination.
Cmn
android
Unit
addDeepLink(uriPattern: String)

Add a deep link to this destination.
Cmn
android
open operator Boolean
equals(other: Any?)
android
String?
fillInLabel(context: Context, bundle: Bundle?)

Parses a dynamic label containing arguments into a String.
android
NavAction?

Returns the NavAction for the given action ID.
android
open Boolean
hasDeepLink(deepLink: NavUri)

Checks the given deep link NavUri, and determines whether it matches a Uri pattern added to the destination by a call to addDeepLink .
Cmn
open Boolean
hasDeepLink(deepLinkRequest: NavDeepLinkRequest)

Checks the given NavDeepLinkRequest, and determines whether it matches a NavDeepLink added to the destination by a call to addDeepLink.
Cmn
android
open Boolean
hasDeepLink(deepLink: Uri)
android
open Int
android
open Unit

Called when inflating a destination from a resource.
android
Unit
putAction(actionId: @IdRes Int, action: NavAction)

Sets the NavAction destination for an action ID.
android
Unit
putAction(actionId: @IdRes Int, destId: @IdRes Int)

Creates a NavAction for the given destId and associates it with the actionId.
android
Unit
removeAction(actionId: @IdRes Int)

Unsets the NavAction for an action ID.
android
Unit
removeArgument(argumentName: String)

Unsets the argument type for an argument name.
Cmn
android
open String
android

Public properties
Map<String, NavArgument>

The arguments supported by this destination.
Cmn
android
open String
Cmn
Int

The destination's unique ID.
Cmn
android
CharSequence?

The descriptive label of this destination.
Cmn
android
String

The name associated with this destination's Navigator.
Cmn
android
NavGraph?

Gets the NavGraph that contains this destination.
Cmn
android
String?

The destination's unique route.
Cmn
android

Public companion functions

hasRoute

Cmn android 
inline fun <T : Any> NavDestination.hasRoute(): Boolean

Checks if the NavDestination's route was generated from T

Returns true if equal, false otherwise.

Parameters
<T : Any>

the route from KClass

hasRoute

Cmn android 
fun <T : Any> NavDestination.hasRoute(route: KClass<T>): Boolean

Checks if the NavDestination's route was generated from T

Returns true if equal, false otherwise.

Parameters
route: KClass<T>

the route from KClass

Protected companion functions

parseClassFromName

android
Added in 2.4.0
protected fun <C : Any?> parseClassFromName(
    context: Context,
    name: String,
    expectedClassType: Class<C?>
): Class<C?>

Parse the class associated with this destination from a raw name, generally extracted from the android:name attribute added to the destination's XML. This should be the class providing the visual representation of the destination that the user sees after navigating to this destination.

This method does name -> Class caching and should be strongly preferred over doing your own parsing if your Navigator supports the android:name attribute to give consistent behavior across all Navigators.

Parameters
context: Context

Context providing the package name for use with relative class names and the ClassLoader
name: String

Absolute or relative class name. Null names will be ignored.
expectedClassType: Class<C?>

The expected class type
Returns
Class<C?>

The parsed class
Throws
kotlin.IllegalArgumentException

if the class is not found in the provided Context's ClassLoader or if the class is not of the expected type

Public companion properties

hierarchy

Cmn android 
val NavDestination.hierarchy: Sequence<NavDestination>

Provides a sequence of the NavDestination's hierarchy. The hierarchy starts with this destination itself and is then followed by this destination's NavDestination.parent, then that graph's parent, and up the hierarchy until you've reached the root navigation graph.

Public constructors

Cmn android
Added in 1.0.0
NavDestination(navigatorName: String)
Cmn android
Added in 1.0.0
NavDestination(navigator: Navigator<NavDestination>)

NavDestinations should be created via Navigator.createDestination.

This constructor requires that the given Navigator has a Navigator.Name annotation.

Public functions

addArgument

Cmn android
Added in 1.0.0
fun addArgument(argumentName: String, argument: NavArgument): Unit

Sets an argument type for an argument name

Parameters
argumentName: String

argument object to associate with destination
argument: NavArgument

argument object to associate with destination

addDeepLink

Cmn android
Added in 2.3.0
fun addDeepLink(navDeepLink: NavDeepLink): Unit

Add a deep link to this destination. Uris that match the given NavDeepLink uri sent to NavController.handleDeepLink or NavController.navigate will trigger navigating to this destination.

In addition to a direct Uri match, the following features are supported:

Uris without a scheme are assumed as http and https. For example, www.example.com will match http://www.example.com and https://www.example.com. Placeholders in the form of {placeholder_name} matches 1 or more characters. The String value of the placeholder will be available in the arguments SavedState with a key of the same name. For example, http://www.example.com/users/{id} will match http://www.example.com/users/4. The .* wildcard can be used to match 0 or more characters.

These Uris can be declared in your navigation XML files by adding one or more <deepLink app:uri="uriPattern" /> elements as a child to your destination.

Custom actions and mimetypes are also supported by NavDeepLink and can be declared in your navigation XML files by adding <app:action="android.intent.action.SOME_ACTION" /> or <app:mimetype="type/subtype" /> as part of your deepLink declaration.

Deep link Uris, actions, and mimetypes added in navigation XML files will automatically replace instances of ${applicationId} with the applicationId of your app. Programmatically added deep links should use Context.getPackageName directly when constructing the uriPattern.

When matching deep links for calls to NavController.handleDeepLink or NavController.navigate the order of precedence is as follows: the deep link with the most matching arguments will be chosen, followed by the deep link with a matching action, followed by the best matching mimeType (e.i. when matching mimeType image/jpg: image/ * *\/jpg *\/ *).

Parameters
navDeepLink: NavDeepLink

The NavDeepLink to add as a deep link
See also
handleDeepLink
navigate

addDeepLink

Cmn android
Added in 1.0.0
fun addDeepLink(uriPattern: String): Unit

Add a deep link to this destination. Matching Uris sent to NavController.handleDeepLink or NavController.navigate will trigger navigating to this destination.

In addition to a direct Uri match, the following features are supported:

  • Uris without a scheme are assumed as http and https. For example, www.example.com will match http://www.example.com and https://www.example.com.

  • Placeholders in the form of {placeholder_name} matches 1 or more characters. The parsed value of the placeholder will be available in the arguments SavedState with a key of the same name. For example, http://www.example.com/users/{id} will match http://www.example.com/users/4.

  • The .* wildcard can be used to match 0 or more characters.

These Uris can be declared in your navigation XML files by adding one or more <deepLink app:uri="uriPattern" /> elements as a child to your destination.

Deep links added in navigation XML files will automatically replace instances of ${applicationId} with the applicationId of your app. Programmatically added deep links should use Context.getPackageName directly when constructing the uriPattern.

Parameters
uriPattern: String

The uri pattern to add as a deep link
See also
handleDeepLink
navigate
addDeepLink

equals

android 
open operator fun equals(other: Any?): Boolean

fillInLabel

android
Added in 2.6.0
fun fillInLabel(context: Context, bundle: Bundle?): String?

Parses a dynamic label containing arguments into a String.

Supports String Resource arguments by parsing R.string values of ReferenceType arguments found in android:label into their String values.

Returns null if label is null.

Returns the original label if the label was a static string.

Parameters
context: Context

Context used to resolve a resource's name
bundle: Bundle?

SavedState containing the arguments used in the label
Returns
String?

The parsed string or null if the label is null
Throws
kotlin.IllegalArgumentException

if an argument provided in the label cannot be found in the bundle, or if the label contains a string template but the bundle is null

getAction

android
Added in 1.0.0
fun getAction(id: @IdRes Int): NavAction?

Returns the NavAction for the given action ID. This will recursively check the getParent of this destination if the action destination is not found in this destination.

Parameters
id: @IdRes Int

action ID to fetch
Returns
NavAction?

the NavAction mapped to the given action id, or null if one has not been set

hasDeepLink

Cmn 
open fun hasDeepLink(deepLink: NavUri): Boolean

Checks the given deep link NavUri, and determines whether it matches a Uri pattern added to the destination by a call to addDeepLink . It returns true if the deep link is a valid match, and false otherwise.

This should be called prior to NavController.navigate to ensure the deep link can be navigated to.

Parameters
deepLink: NavUri

to the destination reachable from the current NavGraph
Returns
Boolean

True if the deepLink exists for the destination.
See also
addDeepLink
navigate
hasDeepLink

hasDeepLink

Cmn android
Added in 2.3.0
open fun hasDeepLink(deepLinkRequest: NavDeepLinkRequest): Boolean

Checks the given NavDeepLinkRequest, and determines whether it matches a NavDeepLink added to the destination by a call to addDeepLink. It returns true if the request is a valid match, and false otherwise.

This should be called prior to NavController.navigate to ensure the deep link can be navigated to.

Parameters
deepLinkRequest: NavDeepLinkRequest

to the destination reachable from the current NavGraph
Returns
Boolean

True if the deepLink exists for the destination.
See also
addDeepLink
navigate

hasDeepLink

android
Added in 2.1.0
open fun hasDeepLink(deepLink: Uri): Boolean

hashCode

android 
open fun hashCode(): Int

onInflate

android
Added in 1.0.0
@CallSuper
open fun onInflate(context: Context, attrs: AttributeSet): Unit

Called when inflating a destination from a resource.

Parameters
context: Context

local context performing inflation
attrs: AttributeSet

attrs to parse during inflation

putAction

android
Added in 1.0.0
fun putAction(actionId: @IdRes Int, action: NavAction): Unit

Sets the NavAction destination for an action ID.

Parameters
actionId: @IdRes Int

action ID to bind
action: NavAction

action to associate with this action ID
Throws
kotlin.UnsupportedOperationException

this destination is considered a terminal destination and does not support actions

putAction

android
Added in 1.0.0
fun putAction(actionId: @IdRes Int, destId: @IdRes Int): Unit

Creates a NavAction for the given destId and associates it with the actionId.

Parameters
actionId: @IdRes Int

action ID to bind
destId: @IdRes Int

destination ID for the given action

removeAction

android
Added in 1.0.0
fun removeAction(actionId: @IdRes Int): Unit

Unsets the NavAction for an action ID.

Parameters
actionId: @IdRes Int

action ID to remove

removeArgument

Cmn android
Added in 1.0.0
fun removeArgument(argumentName: String): Unit

Unsets the argument type for an argument name.

Parameters
argumentName: String

argument to remove

toString

android 
open fun toString(): String

Public properties

arguments

Cmn android
Added in 1.0.0
val arguments: Map<String, NavArgument>

The arguments supported by this destination. Returns a read-only map of argument names to NavArgument objects that can be used to check the type, default value and nullability of the argument.

To add and remove arguments for this NavDestination use addArgument and removeArgument.

Returns
Map<String, NavArgument>

Read-only map of argument names to arguments.

displayName

Cmn 
open val displayName: String

id

Cmn android
Added in 1.0.0
var id: Int

The destination's unique ID. This should be an ID resource generated by the Android resource system.

If using safe args, setting this manually will override the ID that was set based on route from KClass.

label

Cmn android
Added in 1.0.0
var label: CharSequence?

The descriptive label of this destination.

Cmn android
Added in 1.0.0
val navigatorName: String

The name associated with this destination's Navigator.

parent

Cmn android
Added in 1.0.0
var parent: NavGraph?

Gets the NavGraph that contains this destination. This will be set when a destination is added to a NavGraph via NavGraph.addDestination.

route

Cmn android
Added in 2.4.0
var route: String?

The destination's unique route. Setting this will also update the id of the destinations so custom destination ids should only be set after setting the route.

Returns
String?

this destination's route, or null if no route is set
Throws
kotlin.IllegalArgumentException

is the given route is empty