Navigation

Navigation is a framework for navigating between 'destinations' within an Android application that provides a consistent API whether destinations are implemented as Fragments, Activities, or other components. See the reference docs for more information.

Declaring dependencies

To add a dependency on Navigation, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
    def nav_version = "2.1.0-alpha02"

    implementation "androidx.navigation:navigation-fragment:$nav_version" // For Kotlin use navigation-fragment-ktx
    implementation "androidx.navigation:navigation-ui:$nav_version" // For Kotlin use navigation-ui-ktx
}

For information on using Kotlin extensions, see the ktx documentation.

For more information about dependencies, see Add Build Dependencies.

SafeArgs

For Safe args, add the following classpath in your top level build.gradle file

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:2.1.0-alpha02"
    }
}

You must also apply one of two available plugins.

To generate Java code suitable for Java or mixed Java and Kotlin modules, add this line to your app or module build.gradle file:

apply plugin: "androidx.navigation.safeargs"

Alternatively, to generate Kotlin code suitable for Kotlin-only modules add:

apply plugin: "androidx.navigation.safeargs.kotlin"

You must have android.useAndroidX=true in your gradle.properties file as per Migrating to AndroidX.

Version 2.1.0-alpha02

April 3rd, 2019

androidx.navigation:*:2.1.0-alpha02 is released. The commits included in this version can be found here.

New features

You can now create ViewModels that are scoped at a navigation graph level via the by navGraphViewModels() property delegate for Kotlin users or by using the getViewModelStore() API added to NavController. b/111614463

API changes

You can now add an app:targetPackage to an <activity> destination to limit the matching package name. It supports app:targetPackage="${applicationId}" for restricting the package to your own application id. b/110975456

Bug fixes

The android:name for <activity> destinations is no longer parsed into a Class at inflation time, preventing ClassNotFoundExceptions when using dynamic features. b/124538597

Version 2.1.0-alpha01

March 19, 2019

This is the first alpha release of Navigation 2.1.0.

Dependency changes

Navigation now depends on androidx.core:core:1.0.1 and androidx.fragment:fragment:1.1.0-alpha05. This release also removes the dependency on androidx.legacy:legacy-support-core-utils:1.0.0. b/128632612

API Changes

A new Navigation.createNavigateOnClickListener(NavDirections) method has been added as an alternative to creating a click listener with a resource ID and Bundle. b/127631752
FragmentNavigator.instantiateFragment is now deprecated. The default implementation now uses FragmentFactory to instantiate Fragments. b/119054429

Bug Fixes

Navigation no longer sends a null Bundle when there are arguments attached to a destination, fixing an issue when using android:defaultValue="@null". b/128531879
Safe Args now depends on KotlinPoet 1.1.0, fixing an issue with extremely long package names. b/123654948

Version 2.0.0

March 14, 2019

Navigation 2.0.0 is released with no changes from 2.0.0-rc02.

Version 2.0.0-rc02

March 6, 2019

Navigation 2.0.0-rc02 provides new artifacts with the androidx.navigation group ID and changes its dependencies to the AndroidX equivalents.

The behavior of 2.0.0-rc02 is identical to behavior to Navigation 1.0.0-rc02 and no changes to your code should be required to update from 1.0.0-rc02 besides updating your dependencies to match the new dependencies.

Your project must have migrated to AndroidX to use 2.X releases of Navigation. Navigation 1.0 stable will be the last release using the Support Library dependencies; all future development beyond 1.0 will be based on AndroidX and build upon the 2.0 stable release.

Pre-AndroidX Dependencies

For the pre-AndroidX versions of Navigation, include these dependencies:

dependencies {
    def nav_version = "1.0.0"

    implementation "android.arch.navigation:navigation-fragment:$nav_version" // For Kotlin use navigation-fragment-ktx
    implementation "android.arch.navigation:navigation-ui:$nav_version" // For Kotlin use navigation-ui-ktx
}

For Safe args, add the following classpath in your top level build.gradle file

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath "android.arch.navigation:navigation-safe-args-gradle-plugin:1.0.0"
    }
}

Version 1.0.0

March 14, 2019

Navigation 1.0.0 is released with no changes from 1.0.0-rc02.

Version 1.0.0-rc02

February 26, 2019

This is the second release candidate for Navigation's 1.0.0 stable release. This release contains a number of bug fixes.

Bug Fixes

Fixed an issue where popBackStack() would be ignored if the root graph did not have an ID b/126251695
navigateUp() now correctly handles navigating back to your app's task when called after handling a deep link without FLAG_ACTIVITY_NEW_TASK b/126082008
Fixed an issue with ActivityNavigator.applyPopAnimationsToPendingTransition not applying the correct pop exit animation b/126237567
Kotlin code generated by Safe Args now properly escapes Kotlin keywords such as in and fun in the package name associated with the R class. b/126020455

Version 1.0.0-rc01

February 21, 2019

This is a release candidate for Navigation's 1.0.0 stable release. This release contains one bug fix.

Bug Fixes

Fixed an issue when using Fragments and singleTop navigation operations b/124294805

Version 1.0.0-beta02

February 12, 2019

This release includes a number of minor improvements and important bug fixes.

New Features

You can now use 0 as an android:defaultValue for reference arguments. b/124248602

Behavior changes

Exact deep link matches are now prioritized over deep links with .* or argument matches. b/123969518

Bug Fixes

popBackStack() and navigateUp now correctly return false when popping the last destination on the back stack, fixing a regression introduced in 1.0.0-beta01. b/123933201
Navigation now correctly sets the ClassLoader during restoration of saved instance state, avoiding issues when using custom classes in Navigator saved state or in arguments sent to a NavDestination. b/123893858
Safe Args generated NavArgs classes no longer crash when restoring a Parcelable[] argument from saved instance state. b/123963545
Safe Args now properly cleans up unnecessary generated Kotlin classes. b/124120883

Version 1.0.0-beta01

February 4, 2019

This is the first beta release of Navigation; moving forward, the Navigation API is expected to stay stable until the next version unless there is a critical problem. This release contains some bug fixes and behavior changes.

Behavior changes

Navigation now ensures that argument default values are treated identically at runtime and through Safe Args. As a consequence, only arguments with an app:argType="reference" can have a default value point to another resource (for example, @color/colorPrimary). Attempting to use a reference default value with a different app:argType will result in an exception when parsing the navigation XML. b/123551990
Safe Args now depends on Android Gradle Plugin 3.3.0 aosp/888413
Safe Args now depends on Kotlin 1.3.20 aosp/888414

Bug Fixes

Safe Args can now be used in library and feature modules on all versions of the Android Gradle Plugin. b/121304903
Fixed a regression that would cause a single popBackStack() operation to pop all copies of a destination off the top of the back stack, rather than just a single destination at a time. b/123552990
Fixed an issue where the FragmentNavigator state would desynchronize with the NavController's state, causing an IllegalStateException when attempting to restore the back stack. b/123803044
Fixed an issue where the NavigationUI handled back arrow would not appear when using ProGuard with obfuscation. b/123449431
The code generated by Safe Args now properly handles using an app:argType pointing to a static inner class in the format .OuterClass$InnerClass. b/123736741
The Java code generated by Safe Args now properly handles global actions and deeply nested destinations. b/123347762

Version 1.0.0-alpha11

January 23, 2019

This is a hotfix release of 1.0.0-alpha10 that fixes an issue with Safe Args.

Bug Fixes

Fixes an issue where Safe Args would fail to import the Directions class associated with global actions. b/123307342

Version 1.0.0-alpha10

January 23, 2019

Known Issues

Safe Args fails to import the Directions class associated with global actions. b/123307342

This release contains breaking API changes; please see the Breaking Changes section below.

New Features

Kotlin users can now use the by navArgs() property delegate to lazily get a reference to a Safe Args generated NavArgs class in an Activity or Fragment. b/122603367
Safe Args now allows you to generate Kotlin code by applying the androidx.navigation.safeargs.kotlin plugin. The Kotlin code is built specifically for Kotlin only modules, using default arguments and immutable classes over the builder pattern that is still available via the previous androidx.navigation.safeargs plugin. b/110263087

Behavior Changes

Matching deep links are now biased towards the deep link that has the most matching arguments. b/118393029
Calling setGraph() on a NavController will now reset the back stack. b/111450672
Unknown deep links no longer throw an IllegalStateException, but are ignored, fixing issues with nested or multiple NavHostFragments. b/121340440

Breaking Changes

The NavOptions.applyPopAnimationsToPendingTransition() method for applying pop animations to an Activity has been moved to ActivityNavigator. b/122413117
Safe Args now avoids duplicating identical classes for actions without arguments. The return type for no argument methods in generated NavDirections classes is now NavDirections. b/123233147
Safe Args generated Directions classes no longer have a public constructor - you should only be interacting with the generated static methods. b/123031660
Safe Args generated NavDirections classes no longer have a public constructor - they should only be generated via the static methods in the generated Directions classes. b/122963206
The returned Bundle from NavDirections' getArguments() is now marked as @NonNull rather than @Nullable. b/123243957

Bug Fixes

NavDeepLinkBuilder now correctly handles multiple simultaneous PendingIntents to the same destination by using the arguments you pass in to determine the uniqueness. b/120042732
NavController now correctly handles popBackStack() operations when using a nested NavHostFragment or other child Fragments with a back stack. b/122770335
NavigationUI now correctly sets the content description of the Up button. b/120395362
Safe Args generated Directions classes now correctly handle global actions that have the same id as an action on a destination. b/122962504
Safe Args generated NavDirections classes now correctly have equal hashCode() values when equals() would return true. b/123043662
FragmentNavigator now throws a better error message if you attempt to do custom FragmentTransactions on the NavHostFragment's FragmentManager. You should always use getChildFragmentManager(). b/112927148

Version 1.0.0-alpha09

December 18, 2018

This release contains breaking API changes; please see the Breaking Changes section below.

We have chosen not to continue development of the android.arch.navigation:navigation-testing artifact. While it has proven helpful for internal testing of NavController, we strongly recommend alternate testing strategies, such as mocking the NavController instance in order to verify that the correct navigate() calls are being done. This approach is discussed in detail in the Single Activity talk at AndroidDevSummit 2018 and we'll be working on additional documentation specifically around testing with Navigation.

New Features

MenuItems with menuCategory="secondary" will no longer pop the back stack when used with NavigationUI methods. b/120104424
AppBarConfiguration now allows you to set a fallback OnNavigateUpListener instance which will be called when navController.navigateUp() returns false. b/79993862 b/120690961

Breaking Changes

When using an <argument> with an argType="reference", Navigation no longer parses the reference, instead providing the raw resource ID itself. b/111736515
onNavDestinationSelected() now pops back to the start destination of your navigation graph by default, making them consistent with the setup methods. Add menuCategory="secondary" to your MenuItem to avoid popping the back stack. aosp/852869
The fromBundle() methods of generated Args classes now take a non-null Bundle instead of a nullable Bundle aosp/845616

Bug Fixes

Arguments are now properly parsed from deep links as the correct argType instead of always as strings b/110273284
Navigation now correctly exports its public resources b/121059552
Safe Args is now compatible with Android Gradle Plugin 3.4 Canary 4 and higher b/119662045

Version 1.0.0-alpha08

December 6, 2918

This release contains breaking API changes; please see the Breaking Changes section below.

New Features

Destination labels, when used with NavigationUI methods, will now automatically replace {argName} instances in your android:label with the correct argument b/80267266
Navigation now depends on Support Library 28.0.0 b/120293333

Breaking Changes

OnNavigatedListener has been renamed to OnDestinationChangedListener b/118670572
OnDestinationChangedListener now also passes the Bundle of arguments aosp/837142
The app:clearTask and app:launchDocument attributes and their associated methods have been removed. Use app:popUpTo with the root of your graph to remove all destinations from your back stack. b/119628354
ActivityNavigator.Extras now uses a Builder pattern and adds the ability to set any Intent.FLAG_ACTIVITY_ flags aosp/828140
NavController.onHandleDeepLink has been renamed to handleDeepLink aosp/836063
Many classes and methods not meant for subclassing, such as NavOptions, NavInflater, NavDeepLinkBuilder, and AppBarConfiguration, have been made final aosp/835681
The deprecated NavHostFragment.setGraph() method has been removed aosp/835684
The deprecated NavigationUI.navigateUp(DrawerLayout, NavController) method has been removed. aosp/835684
Fragment creation has been moved to FragmentNavigator, making it easier to delegate Fragment creation to a FragmentFactory. b/119054429
The constructor for NavGraphNavigator no longer takes a Context aosp/835340
NavigatorProvider is now a class, rather than an interface. The NavigatorProvider returned by getNavigatorProvider() has not changed its functionality. aosp/830660
NavDestination.navigate() has been removed. Call navigate() on the Navigator instead. aosp/830663
Significant refactoring of Navigator, removing the need for OnNavigatorNavigatedListener and instead having navigate return the NavDestination that was navigated to.
Navigator instances can no longer send pop events to the NavController. Consider using a OnBackPressedCallback to intercept back button presses and call navController.popBackStack(). aosp/833716

Bug Fixes

popUpTo now works consistently when the destination is a <navigation> element b/116831650
Fixed a number of bugs that resulted in an IllegalArgumentException when using nested graphs b/118713731 b/113611083 b/113346925 b/113305559
The dataPattern attribute of <activity> destinations will now populate arguments from non-String arguments by calling toString() b/120161365

Safe Args

Safe Args supports Serializable objects, including Enum values. Enum types can set a default value by using the enum literal without the class name (e.g. app:defaultValue="READ") b/111316353
Safe Args supports arrays of all supported types b/111487504
Safe Args now ignores subfolders of resource directories b/117893516
Safe Args adds @Override annotations where appropriate b/117145301

Version 1.0.0-alpha07

October 29, 2018

New Features

A new AppBarConfiguration class allows you to customize which destinations are considered top-level destinations. See the updated documentation for details. b/117333663
You can now pass arguments to the start destination of your graph b/110300470
Deep links now support custom schemes with periods, hyphens, and plus signs. b/112806402

Breaking Changes

The navigation-testing-ktx module has been folded into the navigation-testing artifact and will no longer be published.
The navigation-testing artifact now has a dependency on the Kotlin standard library. The API has been changed to be more consistent with Kotlin conventions, but you can continue to use it for tests written in Java.
Metadata manifest registered navigation graphs are no longer supported. b/118355937
Actions can no longer be attached to <activity> destinations. aosp/785539

Bug Fixes

Deep links now correctly parse query parameters. b/110057514
Activity destinations now correctly apply all enter and exit animations. b/117145284
Fixed crash that occurs after configuration changes when using custom Navigators. b/110763345

Safe Args

Safe args now have a fixed dependency on Android Gradle Plugin 3.2.1. b/113167627
Directions can now be generated for inner classes. b/117407555
Fixed an issue with generating Directions to an <include> graph. b/116542123

Version 1.0.0-alpha06

September 20, 2018

New Features

Shared Element Transitions for Fragment and Activity destinations are now supported b/79665225. For more information, see Implement navigation with the Navigation Architecture Component
Selecting an item in NavigationView will now close any containing bottom sheet b/112158843

API Changes

Breaking Change: The Navigator navigate() method now takes a Navigator.Extras parameter.
NavController's getGraph() method is now NonNull b/112243286

Bug Fixes

NavigationUI.setupWithNavController() no longer leaks views if used with views from individual destinations b/111961977
Navigator onSaveState() is now only called once b/112627079

Safe Args

Navigation destination Directions classes now extend their parent's Directions class if it exists b/79871405
Directions and Args classes now have a useful toString() implementation b/111843389

Version 1.0.0-alpha05

August 10, 2018

Bug Fixes

Fix a bug which cause incorrect backstack behavior. b/111907708
Fix a bug in equals() of Generated Args classes. b/111450897
Fix a build failure in Safe Args. b/109409713
Fix a conversion from resource identifiers to java names b/111602491
Fix error messages about nullability in Safe Args plugin.
Add missing nullability annotations.

Version 1.0.0-alpha04

July 19, 2018

Navigation 1.0.0-alpha04 and the associated Safe Args gradle plugin contains a number of API changes, behavior changes, and bug fixes.

API / Behavior Changes

NavHostFragment will always set the current Fragment as the primary navigation fragment, ensuring that child fragment managers are popped before the outer NavController is popped b/111345778

Safe Args

Breaking Change: app:type has been changed to app:argType to avoid conflicts with other libraries such as ConstraintLayout 2.0.0-alpha1 b/111110548
Error messages from Safe Args are now clickable b/111534438
Args classes now confirms that NonNull attributes are actually not null b/111451769
Additional NonNull annotations have been added to NavDirections and Args generated classes b/111455455 b/111455456

Bug Fixes

Fixed an issue with the system back button after deep linking to a fragment destination b/111515685

Version 1.0.0-alpha03

July 12, 2018

Navigation 1.0.0-alpha03 and the associated Safe Args gradle plugin contains a number of API changes, behavior changes, and bug fixes.

API / Behavior Changes

A NavigationUI.setupWithNavController method for Toolbar has been added b/109868820
A NavigationUI.setupWithNavController method for CollapsingToolbarLayout has been added b/110887183
popBackStack() now returns false when the back stack is empty or when the given destination ID is not in the back stack b/110893637
FragmentNavigator now ignores navigation operations after FragmentManager has saved state, avoiding “Can not perform this action after onSaveInstanceState” exceptions b/110987825

Safe Args

Breaking Change: Non-alphanumeric characters in action and argument names will be replaced by camel casing in the respective NavDirections method names
- E.g. DemoController.index will become setDemoControllerIndex b/79995048
- E.g. action_show_settings will become actionShowSettings b/79642240
Breaking Change: Arguments are now considered non-null by default. To allow null values on string and parcelable arguments, add app:nullable="true" b/79642307
You can now use app:type="long" with defaultValues in the form of “123L” b/79563966
Parcelable arguments are now supported, using a fully qualified class name for app:type. The only default value supported is "@null" b/79563966
Args classes now implement equals() and hashCode() b/79642246
The Safe Args plugin can now be applied to library projects b/80036553
The Safe Args plugin can now be applied to feature projects b/110011752

Bug Fixes

Fixed issues when navigating during Fragment lifecycle methods b/109916080
Fixed issues when navigating through nested graphs multiple times b/110178671
Fixed issues when using setPopUpTo with the first destination in the graph b/109909461
Fixed issue where all app:defaultValue values were being passed as Strings b/110710788
aapt2 bundled with Android Gradle Plugin 3.2 Beta 01 now adds keep rules for every android:name attribute in Navigation XML files b/79874119
Fixed memory leak when replacing the default FragmentNavigator b/110900142

Version 1.0.0-alpha02

June 7, 2018

Behavior Changes

FragmentNavigator now uses setReorderingAllowed(true). b/109826220
Navigation now URLDecodes arguments parsed from deep links URLs. b/79982454

Bug Fixes

Fixed an IllegalStateException when calling navigate from Fragment lifecycle methods. b/79632233
Navigation now depends on Support Library 27.1.1 to fix flickering when using animations. b/80160903
Fixed an IllegalArgumentException when using defaultNavHost="true" as a child fragment. b/79656847
Fixed a StackOverflowError when using NavDeepLinkBuilder. b/109653065
Fixed an IllegalArgumentException when navigating back to a nested graph. b/80453447
Fixed an issue with overlapping Fragments when using launchSingleTop. b/79407969
Navigation now builds the correct synthetic back stack for nested graphs. b/79734195
NavigationUI will now highlight the correct item when using a nested graph as a MenuItem. b/109675998

API Changes

The clearTask attribute for actions and the associated API in NavOptions has been deprecated. b/80338878
The launchDocument attribute for actions and the associated API in NavOptions has been deprecated. b/109806636

Version 1.0.0-alpha01

May 8, 2018

Navigation provides a framework for building in-app navigation. This initial release is 1.0.0-alpha01.