Navigation
Latest Update | Stable Release | Release Candidate | Beta Release | Alpha Release |
---|---|---|---|---|
August 21, 2024 | 2.7.7 | 2.8.0-rc01 | - | - |
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:
Groovy
dependencies { def nav_version = "2.7.7" // Jetpack Compose Integration implementation "androidx.navigation:navigation-compose:$nav_version" // Views/Fragments Integration implementation "androidx.navigation:navigation-fragment:$nav_version" implementation "androidx.navigation:navigation-ui:$nav_version" // Feature module support for Fragments implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version" // Testing Navigation androidTestImplementation "androidx.navigation:navigation-testing:$nav_version" }
Kotlin
dependencies { val nav_version = "2.7.7" // Jetpack Compose integration implementation("androidx.navigation:navigation-compose:$nav_version") // Views/Fragments integration implementation("androidx.navigation:navigation-fragment:$nav_version") implementation("androidx.navigation:navigation-ui:$nav_version") // Feature module support for Fragments implementation("androidx.navigation:navigation-dynamic-features-fragment:$nav_version") // Testing Navigation androidTestImplementation("androidx.navigation:navigation-testing:$nav_version") }
Safe Args
To add Safe Args
to your project, include the following classpath
in your top level build.gradle
file:
Groovy
buildscript { repositories { google() } dependencies { def nav_version = "2.7.7" classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version" } }
Kotlin
buildscript { repositories { google() } dependencies { val nav_version = "2.7.7" classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version") } }
You must also apply one of two available plugins.
To generate Java language code suitable for Java or mixed Java and Kotlin modules, add
this line to your app or module's build.gradle
file:
Groovy
plugins { id 'androidx.navigation.safeargs' }
Kotlin
plugins { id("androidx.navigation.safeargs") }
Alternatively, to generate Kotlin code suitable for Kotlin-only modules add:
Groovy
plugins { id 'androidx.navigation.safeargs.kotlin' }
Kotlin
plugins { id("androidx.navigation.safeargs.kotlin") }
You must have android.useAndroidX=true
in your
gradle.properties
file as per
Migrating to AndroidX.
For information on using Kotlin extensions, see the ktx documentation.
For more information about dependencies, see Add Build Dependencies.
Feedback
Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.
See the Issue Tracker documentation for more information.
Version 2.8
Version 2.8.0-rc01
August 21, 2024
androidx.navigation:navigation-*:2.8.0-rc01
is released. Version 2.8.0-rc01 contains these commits.
Bug Fixes
- Fix navigation crash when passing in top level Enum classes as type safe arguments. (I0ba76, b/358137294)
- Navigation 2.8 now correctly works with SDK 34 and will not swap over to SDK 35 until the 2.9 release along with the rest of the AndroidX libraries. (b/358798728)
Version 2.8.0-beta07
August 7, 2024
androidx.navigation:navigation-*:2.8.0-beta07
is released. Version 2.8.0-beta07 contains these commits.
Known Issues
- Due to b/358137294, only Enums nested in another class are supported out of the box. Top level Enums will be supported in the next release.
Bug Fixes
- When navigating to duplicate or shared destinations, navigation will prioritize going to the closest matching destination from the current location in the graph. (Ic89a4, b/352006850)
- Navigation in safe args now has added a new
NavType.EnumType
. This meansEnum
types no longer require customNavType
s. Note that theEnum
’sSerialName
must be the default fully qualified name. (I66d22, b/346475493) - Navigation in safe args has added built-in support for nullable argument types including
Int?
,Long?
,Float?
,Boolean?
, andEnum<*>?
. (I32d13,I1c580,Ifba66,I978b0,Ide076 , b/351994237) - The
NavGraph
’sstartDestination
will now use the default argument values if thestartDestination
route passed to theNavGraph
is exactly equal to thestartDestination.route
. (I13762, b/354046047)
Version 2.8.0-beta06
July 24, 2024
androidx.navigation:navigation-*:2.8.0-beta06
is released. Version 2.8.0-beta06 contains these commits.
Bug Fixes
- Fixed an issue where the
WrongStartDestinationType
lint checks did not check for Companion objects on the passed in class type, causing lint to fail to detect the error. (I92b09)
Version 2.8.0-beta05
July 10, 2024
androidx.navigation:navigation-*:2.8.0-beta05
is released. Version 2.8.0-beta05 contains these commits.
Bug Fixes
- Fix
singleTop
navigation crash when nestedNavGraphs
share the samestartDestination
route. (I17b94, b/294408596)
Version 2.8.0-beta04
June 26, 2024
androidx.navigation:navigation-*:2.8.0-beta04
is released. Version 2.8.0-beta04 contains these commits.
Bug Fixes
- Navigation now supports navigating with empty strings in path arguments. (Ic5dbd, b/339481310)
- Improve error message for custom serializers declared directly on class fields via
@Serializable(with =...)
to clarify that this is currently an unsupported feature. (I052b0, b/341319151) SavedStateHandleFactory
test api can now be used in non-android tests but will require Robolectric to support argument parsing with Bundles. (I76cdc, b/340966212)- Fixed crash from restoring state when resuming the app after process death with using Type-Safe Navigation in Compose. (Ia8f38, b/341801005)
- Fixed an issue in Navigation Compose where after canceling the Predictive Back Gesture, the
NavBackStackEntry
that the user returns to never returns back to theRESUMED
Lifecycle State. This also ensures the returning destination correctly animates back in instead of snapping into place after a fling. (I97a0c, b/346608857) - When using Predictive back with Navigation Compose, the destination being popped will now have the proper z-order, correctly animating on top of the incoming destination. (I2077b, b/345993681)
Version 2.8.0-beta03
June 12, 2024
androidx.navigation:navigation-*:2.8.0-beta03
is released. Version 2.8.0-beta03 contains these commits.
API Changes
CollectionNavType
has a new abstractemptyCollection()
method. Override this to handle an empty collection passed in as an argument. (Ie4d84, b/341723133)
Bug Fixes
- Added documentation on
NavType.serializeAsValue
andserializeAsValues
to highlight that the final outputs should be Uri encoded. (Ida6bd, b/344943214) - Fixed crash when calling
toRoute<T>
with a nullCollectionNavType
argument. When navigating with a nullCollectionNavType
, the output argument will be the default value declared on your Serializable class, or the return value ofemptyCollection()
if there is no default value. (I84158, Id630f, b/342672856)
Version 2.8.0-beta02
May 29, 2024
androidx.navigation:navigation-*:2.8.0-beta02
is released. Version 2.8.0-beta02 contains these commits.
Bug Fixes
- Fixed
ClassCastException
crash when usingNavBackStackEntry.toRoute
with a nullable customNavType
. (I1c29b, b/342239473) - Fixed Navigation back stack state restoration issues caused when attempting to restore a back stack entry that is not reachable via id from the current destination. Since routes are backed by ids, destinations built with routes were also affected. This also fixes a crash caused by calling
clearBackStack()
that had the same underlying issue. (I423c3, b/339908057)
Version 2.8.0-beta01
May 14, 2024
androidx.navigation:navigation-*:2.8.0-beta01
is released. Version 2.8.0-beta01 contains these commits.
API Changes
SavedStateHandle.toRoute()
now takes in atypeMap
parameter for custom argument types. (Ie39fb, b/339026523)- Added a test API to
navigation-testing
to to create aSavedStateHandle
from a Kotlin Serializable object. (Id4867, b/339080702)
Bug Fixes
- Missing parameter docs for Navigation Kotlin DSL functions have been added. (I26a36)
Version 2.8.0-alpha08
May 1, 2024
androidx.navigation:navigation-*:2.8.0-alpha08
is released. Version 2.8.0-alpha08 contains these commits.
Safe Args in Navigation Compose
- The work to support compile time type safety for Navigation Compose and users of the Navigation Kotlin DSL based on Kotlin Serialization has completed and previously experimental APIs are now stable. (Iea94d, I0eb0d, I873b7, I3a64b, I6c3a2, I11f0b, Ic3032, I8d394, I95710, Ice060, Id0e55, I45f8b, Idcdaf, If5380, I08b23, Ia5c59, b/188693139)
This functionality uses Kotlin Serialization to allow you to define destinations in your navigation graph via type safe objects and data classes:
// Define a home destination that doesn't take any arguments
@Serializable
object Home
// Define a profile destination that takes an ID
@Serializable
data class Profile(val id: String)
// Now define your NavHost using type safe objects
NavHost(navController, startDestination = Home) {
composable<Home> {
HomeScreen(onNavigateToProfile = { id ->
navController.navigate(Profile(id))
})
}
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(profile)
}
}
See the Navigation Compose meet Type Safety blog post for more information.
New Features
- The
navigation-fragment-compose
artifact now provides aLocalFragment
composition local to composable methods within aComposableFragment
. (If35e5) NavType
now has built-in support for Lists of Int, String, Boolean, Float, and Long. (I4b6dd, Ia914c, b/188693139)
Version 2.8.0-alpha07
April 17, 2024
androidx.navigation:navigation-*:2.8.0-alpha07
is released. Version 2.8.0-alpha07 contains these commits.
New Features
Adds a new
navigation-fragment-compose
artifact that includes aComposableNavHostFragment
alternative toNavHostFragment
that allows you to addcomposable
destinations to your Navigation XML files. Eachcomposable
destination must be expressed as a top-level, no argument@Composable
method whose fully qualified name is used as theandroid:name
attribute on each destination. When navigating to one of these destinations, a containing fragment is created to display the composable content. (I0ef2e, b/265480755)// In HomeScreen.kt @Composable fun HomeScreen() { // Your Composable content here }
// In your navigation.xml <composable android:id="@+id/home_screen" android:name="com.example.HomeScreenKt\$HomeScreen" />
API Changes
- Support for Safe Args in Navigation Compose using an approach based on Kotlin Serialization continued. These APIs are not finished and are marked with the
ExperimentalSafeArgsApi
annotation. This annotation will be removed when the entire API surface is complete in a future release. (Iefd95, I409c8, I5b5ac, I7e753, I960f8, I3eabd, I8ed5a, Ied2c9, I9b73c, I554db, Ib3aba, Ia668d, b/188693139)
Version 2.8.0-alpha06
April 3, 2024
androidx.navigation:navigation-*:2.8.0-alpha06
is released. Version 2.8.0-alpha06 contains these commits.
API Changes
- Support for Safe Args in Navigation Compose using an approach based on Kotlin Serialization has begun. These APIs are not finished and are marked with the
ExperimentalSafeArgsApi
annotation. This annotation will be removed when the entire API surface is complete in a future release. (I644e7, I98896, I2a1c5, I43a51, I836a1, Ic5eec, I39407, I24e41, If9e14, Ibb13e, If44d3, Icb70f, I8972f, I1d432, Icf32b, I20a14, I262aa, I7de99, I35990, I1033d, b/188693139)
Bug Fixes
NavHost
now usedAlignment.TopStart
as the default contentAlignment argument. This puts it in line with the default forAnimatedContent
and fixes some instances of an unexpected scale from center transition. (I09e72, b/330111602)- When flicking the predictive back gesture while using Navigation Compose, the
NavHost
will now correctly complete the custom transition instead of immediately finishing. (I99017, b/327292110)
Version 2.8.0-alpha05
March 20, 2024
androidx.navigation:navigation-*:2.8.0-alpha05
is released. Version 2.8.0-alpha05 contains these commits.
New Features
- You can now pass arguments to
NavGraph
'sstartDestination
directly in thestartDestination
route without relying ondefaultValue
. This applies to nestedNavGraph
startDestinations
as well. (I0e0b5, b/109505019, b/188693139)
API Changes
- Added new abstract
CollectionNavType<T>
class, a subclass ofNavType<T>
for collection-based arguments such as list, arrays, maps. (Ic6d63, b/188693139) - All of the default
NavType
arrays (IntArrayType
,LongArrayType
,FloatArrayType
,BoolArrayType
, andStringArrayType
) are now of typeCollectionNavType
(Idcf79, b/188693139) NavType
now provides a new openvalueEquals
API that determines if two values of the same type are equal to one another. (I6cb97, b/327229511)
Bug Fixes
- Query parameters in deep links now allows values in the form of curly braces around argument name (i.e.
{argName}
) as valid values for string-basedNavTypes
. This fixes an issue where such a value would be considered invalid (or absence of value) for all types. (I18302, b/327274038) NavController
functions that support routes such asnavigate
orpopBackStack
can now properly match routes filled with arguments of ArrayNavTypes
. (Iea805, b/327229511)
Version 2.8.0-alpha04
March 6, 2024
androidx.navigation:navigation-*:2.8.0-alpha04
is released. Version 2.8.0-alpha04 contains these commits.
New Features
- You can now specify the
SizeTranform
for your transitions in Navigation Compose by defining them as part of the initialization for thecomposable
and/ornavigation
functions. (I91062, b/296912651)
Bug Fixes
- Fixed an issue where
NavHost
in Compose Navigation failed to properly show the transition when using System Back without a gesture. (Iceeae, b/325998468)
Version 2.8.0-alpha03
February 21, 2024
androidx.navigation:navigation-*:2.8.0-alpha03
is released. Version 2.8.0-alpha03 contains these commits.
API Changes
NavBackStackEntry.savedStateHandle
is now marked as@MainThread
as it uses code that is required to be on the main thread anyway. (Ibb988, b/299523245)
Bug Fixes
- Fixed an issue in Navigation that caused
NavGraph
ViewModels to beDESTROYED
too soon because the associated entry’sViewModel
was not part of the saved state. (Ib6bb7, b/317581849)
Dependency Update
- Navigation Compose now depends on Compose 1.7.0-alpha03.
Version 2.8.0-alpha02
February 7, 2024
androidx.navigation:navigation-*:2.8.0-alpha02
is released. Version 2.8.0-alpha02 contains these commits.
New Features
- Navigation Compose now provides support for Predictive in-app back via the new
SeekableTransitionState
APIs from compose-animation. This allows you to use the back gesture to see the previous destination with your custom Transition before deciding to either commit the transaction via the completed gesture or cancel. (I8b8e9)
Version 2.8.0-alpha01
January 24, 2024
androidx.navigation:navigation-*:2.8.0-alpha01
is released. Version 2.8.0-alpha01 contains these commits.
Bug Fixes
- Fixed
BackStackState
leak where multiplesaveState
calls on a destination would result in multiple states to be saved, but only the first one could be restored. (I598b0, b/309559751) - Fixed an issue where non-String arguments would not be properly displayed when using the
NavigationUI
helpers to populate the title of app bars. (#636, b/316676794)
Dependency Update
- Navigation Compose now depends on Compose
1.7.0-alpha01
fixing an issue that could cause an unexpected scale animation. (b/297258205)
External Contribution
- Thanks SimonMarquis for fixing the display issue for non-String arguments when using the
NavigationUI
helpers to populate the title of app bars.
Version 2.7.7
Version 2.7.7
February 7, 2024
androidx.navigation:navigation-*:2.7.7
is released. Version 2.7.7 contains these commits.
Bug Fixes
- Backported from Navigation
2.8.0-alpha01
: FixedBackStackState
leak where multiplesaveState()
calls on a singleNavBackStackEntry
would result in multiple states being saved, but only the first saved state could be restored. (I598b0, b/309559751) - Backported from Navigation
2.8.0-alpha01
: Fixed an issue where non-String arguments would not be properly displayed when using theNavigationUI
helpers to populate the title of app bars. (#636, b/316676794)
External Contribution
- Thanks SimonMarquis for fixing the display issue for non-String arguments when using the
NavigationUI
helpers to populate the title of app bars.
Version 2.7.6
Version 2.7.6
December 13, 2023
androidx.navigation:navigation-*:2.7.6
is released. Version 2.7.6 contains these commits.
Bug Fixes
- The
NavGraph
equals()
function now correctly considers the nodes of the other graph instead of just the calling one. This will ensure that graphs that have nodes with different ids will no longer be considered equal (I401cb, b/311414915)
Version 2.7.5
Version 2.7.5
November 1, 2023
androidx.navigation:navigation-*:2.7.5
is released. Version 2.7.5 contains these commits.
Performance Improvements
- Greatly improved the performance (both in terms of time and number of allocations) of comparing two graphs. This means that calls such as
setGraph
which internally compare the new graph to the existing one are much faster and result in fewer skipped frames. Thank you Michał Z for the thorough analysis that led to this improvement. (I6ad62) NavHost
will now render the start destination on the first composition pass instead of needing to wait for the second pass to read updated state. (I439a7, b/304852206)
Bug Fixes
- Fixed an issue where your back stack would be popped if you called
setGraph
more than once with the exact same graph only if there was a destination in your graph that contained an action linking two destinations. (Ieaed7) - Dialogs that were navigated to and dismissed in quick succession will no longer leak into the list of
NavController.visibleEntries
. (I67586, b/287969970) - When an entry is popped followed by a configuration change, the entry's
ViewModel
will now be cleared properly ifsaveState
is false. (Idf242, b/298164648) - Fixed an issue where
NavController
could handle the same deep link more than once if the back stack was entirely empty before a configuration change or call tosetGraph
only when the incoming Intent had theFLAG_ACTIVITY_NEW_TASK
flag set. (I73c7f)
Dependency Updates
- Navigation with Fragments now depends on Fragment 1.6.2, fixing an issue where the
ViewModel
instances of nested fragments would not be cleared when callingclearBackStack
.
Version 2.7.4
Version 2.7.4
October 4, 2023
androidx.navigation:navigation-*:2.7.4
is released. Version 2.7.4 contains these commits.
New Features
- Added support for
popUpTo
to use routes with arguments to allow popping back to a specific entry that uses those exact arguments, matching the support found inpopBackStack
. (I731f4, b/299255572)
Bug Fixes
- Fix issue where interrupting a navigate with another navigate with
popUpTo
will causeFragmentNavigator
to crash. (I3c848, b/301887045) - Fixed issue where system back press caused the
currentDestination
to not be updated correctly to match the displayed Fragment. (Id0d6c, b/289877514) DialogFragment
lifecycle will now properly move toRESUMED
state when the dialog above it is dismissed. (I88f0d, b/301811387)
Version 2.7.3
Version 2.7.3
September 20, 2023
androidx.navigation:navigation-*:2.7.3
is released. Version 2.7.3 contains these commits.
Bug Fixes
- Fixed an issue in Navigation with Fragments that caused the
visibleEntries
list to contain incorrect entries. (I5caa9, b/288520638) - Fixed an issue that caused Floating Window destination (i.e.
Dialogs
,Bottomsheets
, etc) to never get aRESUMED
Lifecycle callback. (I3b866, b/287505132)
Version 2.7.2
Version 2.7.2
September 6, 2023
androidx.navigation:navigation-*:2.7.2
is released. Version 2.7.2 contains these commits.
Bug Fixes
- Navigation now depends on Lifecycle
2.6.2
, fixing an interaction betweenrememberSaveable
and Navigation Compose’sNavHost
that would cause therememberSaveable
state of destinations and anyViewModel
ownedSavedStateHandle
instances from being properly restored after process death and recreation. (b/298059596, b/289436035) - Fixed an issue when showing multiple dialogs in Navigation Compose simultaneously where the partially obscured dialogs (e.g., not the topmost dialog) would be in the
CREATED
Lifecycle state rather than theSTARTED
state. (aosp/2728520, b/289257213) - Fixed an issue when showing multiple dialogs in Navigation Compose simultaneously where dismissing the topmost dialog would cause the new topmost dialog to be stuck in the
STARTED
Lifecycle state rather than correctly moving toRESUMED
. (aosp/2629401, b/286371387) - Navigation Safe Args no longer instantiates its task eagerly if it is not actually being executed. (I0e385, b/260322841)
Dependency Update
- Navigation Compose now depends on Compose 1.5.1.
Version 2.7.1
Version 2.7.1
August 23, 2023
androidx.navigation:navigation-*:2.7.1
is released. Version 2.7.1 contains these commits.
Bug Fixes
- Fixed an issues in Navigation with Compose where when using a
Scaffold
it was possible to get an error for trying to access aLifecycle.State.DESTROYED
ViewModel
. (I1dc11, b/268422136)
Version 2.7.0
Version 2.7.0
August 9, 2023
androidx.navigation:navigation-*:2.7.0
is released. Version 2.7.0 contains these commits.
Important changes since 2.6.0
Animations from Accompanist
Now that AnimatedContent
is stable, we were able to move the code from Accompanist Navigation Animation back into Navigation Compose itself.
This means all of the support for setting custom transitions that existed in AnimatedNavHost
is directly supported in NavHost
.
No additional changes will be made to Accompanist Navigation Animation and we’ll be formally deprecating it soon, along with guidance on how to migrate back to Navigation Compose itself, but it'll be the inverse of the migration guide with no other API changes required if you're already using the latest Accompanist alpha (0.31.2-alpha
). (b/197140101)
Bug Fixes
- NavHost in Navigation Compose now correctly intercepts system back calls even after the Activity has been STOPPED and RESUMED. (Icb6de, b/279118447)
Dependency Updates
- Navigation now depends on Compose
1.5.0
up from1.1.0
.
Version 2.7.0-rc01
July 26, 2023
androidx.navigation:navigation-*:2.7.0-rc01
is released. Version 2.7.0-rc01 contains these commits.
Bug Fixes
- Fixed an issue where the
EnterTransition
andExitTransition
lambdas created as part of theNavHost
could potentially remain in memory even after theNavHost
is removed from composition. (I893d0)
Known Issues
- There is an issue from Navigation 2.6.x that when navigating with popUpTo it is possible to cause an
IllegalArgumentException
. It is possible that this exception can be avoided by restructuring your graph, similar to the advice suggested here. (b/287133013)
Version 2.7.0-beta02
June 28, 2023
androidx.navigation:navigation-*:2.7.0-beta02
is released. Version 2.7.0-beta02 contains these commits.
Bug Fixes
- Navigation Compose now has the right z-order for custom transitions that use navigate with the
popUpTo
option.(/Ib1c3a, b/285153947)
Version 2.7.0-beta01
June 7, 2023
androidx.navigation:navigation-*:2.7.0-beta01
is released. Version 2.7.0-beta01 contains these commits.
Bug Fixes
NavHost
in Navigation Compose now correctly intercepts system back calls even after theActivity
has beenSTOPPED
andRESUMED
. (Icb6de, b/279118447)
Version 2.7.0-alpha01
May 24, 2023
androidx.navigation:navigation-*:2.7.0-alpha01
is released. Version 2.7.0-alpha01 contains these commits.
Animations from Accompanist
Now that AnimatedContent
is stable, we were able to move the code from Accompanist Navigation Animation back into Navigation Compose itself.
This means all of the support for setting custom transitions that existed in AnimatedNavHost
is directly supported in NavHost
.
No additional changes will be made to Accompanist Navigation Animation and we’ll be formally deprecating it soon, along with guidance on how to migrate back to Navigation Compose itself, but it'll be the inverse of the migration guide with no other API changes required if you're already using the latest Accompanist alpha (0.31.2-alpha
). (b/197140101)
Bug Fixes
- From Navigation
2.6.0-rc02
: Fixed an issue with Navigation in Fragments where navigating withpopUpTo
and popping a fragment off the back stack without recreating its view would cause system back to stop working. (Ieb8d4, b/281726455)
Dependency Updates
- Navigation now depends on Compose
1.5.0-beta01
.
Version 2.6.0
Version 2.6.0
June 7, 2023
androidx.navigation:navigation-*:2.6.0
is released. Version 2.6.0 contains these commits.
Important changes to Navigation since 2.5.0
NavBackStackEntry
'sarguments
and thearguments
passed to anOnDestinationChangedListener
are now only a copy of the immutable arguments that were created when you navigated to the destination. This means any changes made to those Bundles will not be reflected in subsequent accesses to thearguments
or otherOnDestinationChangedListener
instances.NavDeepLink
now supports default values for arrays, which allows support for repeated query params that will map to the argument's array type.NavType
also now includes a default method which can be overridden to combine two parsed values.- Custom subclasses of
NavType
can now overrideserializeAsValue
to serialize a value into a String, allowing both serialization and deserialization (viaparseValue
) to be entirely encapsulated in theNavType
class.StringType
now overrides this method to callUri.encode
on the givenString
.
Important changes to Navigation Compose since 2.5.0
- When previewing a composable with
NavHost
, it will now show the NavGraph'sstartDestination
by default. NavController.popBackStack(route)
,NavController.getBackStackEntry(route)
,NavController.clearBackStack(route)
now all support routes with arguments partially or fully filled in. Note that the arguments have to be an exact match with the entry's arguments.- Attempting to create an empty
NavDeepLink
using thenavDeepLink
Kotlin DSL will now result in a lint warning indicating that a deep link needs an uri, action, and/or mimetype to be valid.
Important changes to Navigation with Fragments since 2.5.0
NavHostFragment
no longer intercepts the system back button itself. This allows the underlyingFragmentManager
to handle system back. This allows Fragment1.7.0-alpha01
and higher to provide an In-App Predictive Back animation on Android U devices.- When using Navigation with Fragments, attempting to manually do a
FragmentTransaction
that adds a fragment to theFragmentManager
's back stack will now throw anIllegalArgumentException
. You should always add fragments via thenavigate()
API. - When using the exact string
${applicationId}
as the placeholder in theapp:data
andapp:dataPattern
attributes in the activity element of a navigation XML file, the placeholder will be automatically filled in with thepackageName
of the context upon inflation. - The
FragmentNavigator
now uses the transition APIs when navigating and poppingNavBackStackEntries
. This means that theNavBackStackEntry
Lifecycle
will now wait for the entering and exiting fragment special effects to complete before moving their finalLifecycle.State
. - The
DialogFragmentNavigator
now uses the transition APIs when navigating and poppingNavBackStackEntries
. This means that theNavBackStackEntry
Lifecycle
will now wait for theDialogFragment
Lifecycle
to move toDESTROYED
before moving toDESTROYED
itself. NavHostFragment
now allows you to retrieve theNavController
as soon as theNavHostFragment
is attached to theFragmentManager
, rather than only afteronCreate()
.- Navigation's support for Dynamic Feature Modules now depend on the granular Play Feature Delivery Library.
- Navigation Safe Args now depends on Android Gradle Plugin version 7.3.0. This means it is now only compatible with versions 7.3.0+.
Important changes to NavigationUI since 2.5.0
- When passing the ID of a navigation graph to
AppBarConfiguration
(such as via aMenu
),NavigationUI
now only considers the start destination of that navigation graph as a top level destination, rather than incorrectly marking every destination within the graph as a top level destination. The behavior of passing the ID of an individual destination is unchanged. This same functionality is available to your own code via the newisTopLevelDestination
function onAppBarConfiguration
. - The
setupWithNavController
integrations inNavigationUI
for working with the top app bar will now parseR.string
values forReferenceType
arguments found in yourandroid:label
into their String values instead of outputting the auto-generated resource integer. NavigationUI
now provides logs when it fails to navigate via a selectedMenuItem
.
Version 2.6.0-rc02
May 24, 2023
androidx.navigation:navigation-*:2.6.0-rc02
is released. Version 2.6.0-rc02 contains these commits.
Bug Fixes
- Fixed an issue with Navigation in Fragments where navigating with
popUpTo
and popping a fragment off the back stack without recreating its view would cause system back to stop working. (Ieb8d4, b/281726455)
Version 2.6.0-rc01
May 10, 2023
androidx.navigation:navigation-*:2.6.0-rc01
is released. Version 2.6.0-rc01 contains these commits.
Bug Fixes
- Fixed an issue in Navigation with fragments where removing a fragment via navigate with
popUpTo
in itsonResume()
lifecycle callback would cause anIllegalStateException
. (I21884, b/279644470)
Version 2.6.0-beta01
April 19, 2023
androidx.navigation:navigation-*:2.6.0-beta01
is released. Version 2.6.0-beta01 contains these commits.
New Features
NavBackStackEntry
now provides a customtoString
implementation. (Iff00b)
Bug Fixes
- When using Navigation with Fragments, attempting to manually do a
FragmentTransaction
that adds a fragment to theFragmentManager
's back stack will now throw anIllegalArgumentException
. You should always add fragments via thenavigate()
API. (I6d38e) - When there is a
navigate
that adds an entry and apopBackStack
that removes it in the same frame, the resulting top entry on the back stack will now consistently make it back to theRESUMED
Lifecycle.State
. (Id8067, b/276495952)
Version 2.6.0-alpha09
April 5, 2023
androidx.navigation:navigation-*:2.6.0-alpha09
is released. Version 2.6.0-alpha09 contains these commits.
Bug Fixes
- Fixed checks for invalid route such that if a
NavDestination
contains non-nullableNavArgument
, this destination's route must contain placeholders for args named the same as the non-nullableNavArgument
. (Ic62bf, b/274697949) - Deeplink navigations based on
Action/MimeType
will now fail if the navigation operation is missing a non-nullableNavArgument
required by theNavDestination
that theAction/MimeType
matches with. (Ibfa17, b/271777424) - When
NavController
sets a graph with the same route and destinations as the previous graph, it now properly replaces its current graph nodes and its back stack destinations with new instances. This fixes a crash when usingonLaunchSingleTop
without saving state in Navigation Compose. This also fixes an error where navigating to destinations associated with the root graph builds and incorrect back stack. (I5bc58, b/275258161, b/275407804)
Version 2.6.0-alpha08
March 22, 2023
androidx.navigation:navigation-*:2.6.0-alpha08
is released. Version 2.6.0-alpha08 contains these commits.
New Features
NavHostFragment
now allows you to retrieve theNavController
as soon as theNavHostFragment
is attached to theFragmentManager
, rather than only afteronCreate()
. (Ic6382, b/220186282)
Bug Fixes
- Fixed a
NullPointerException
when popping a nested graph that includes a non-nullable argument. (6b3581, b/249988437) - When using system back after doing a navigate with
popUpTo
, the state of theNavController
will pop to the correct entry. (I3a8ec, b/270447657) FragmentNavigator
will now properly pop entries when the back stack is popped via system back orpopBackStack()
and whether or not the transaction uses effects for the fragment. (I81bdf)- Adding fragments to the
FragmentNavigator
'sFragmentManager
without using navigation will no longer cause a crash. (b17204, b/274167493)
Dependency Updates
- Navigation now depends on Lifecycle
2.6.1
. (586fe7) - Navigation now depends on SavedState
1.2.1
. (078e4e) - Navigation now depends on ProfileInstaller
1.3.0
. (512f0c)
Version 2.6.0-alpha07
March 8, 2023
androidx.navigation:navigation-*:2.6.0-alpha07
is released. Version 2.6.0-alpha07 contains these commits.
Bug Fixes
- The
getBackStackEntry
,popBackStack
,clearBackStack
API variants that take routes now take route patterns with nullable arguments and nullable query params (I22294, b/269302500) - Fixed an issue where calling
clearBackStack()
from theNavController
would not clear the saved state in the fragment manager associated with the cleared back stack. (Ic1cce, b/271190202) - Fixed a regression in 2.6.0-alpha06 that caused the wrong
MenuItem
in theBottomNavigationView
to be highlighted when using System back between tabs. (I634f6, b/270447657) - Fixed regression in 2.6.0-alpha06 that caused
NavBackStackEntry
s not to be moved to the RESUMED state when usingAnimation
s. (Ib3589, b/269646882)
Version 2.6.0-alpha06
February 22, 2023
androidx.navigation:navigation-*:2.6.0-alpha06
is released. Version 2.6.0-alpha06 contains these commits.
New features
- When previewing a composable with
NavHost
, it will now show the NavGraph'sstartDestination
by default. (I2b89f)
API Changes
- All
NavController
navigate
overloads are now annotated with@MainThread
to ensure that they are called on the main thread. (I2c0b0, b/263427111)
Bug Fixes
- Fixed a crash when attempting to navigate while using Dynamic Fragment Navigation. (I3ee29, b/268360479)
- Fixed bug where navigating to another fragment via system back button does not update bottom bar to the correct selected item (If559f, b/269044426)
Known Issues
- When using Navigation with Fragments, the
NavBackStackEntry
's Lifecycle fails to reachRESUMED
when usingAnimation
APIs. (b/269646882) - When using Navigation with Fragments, and navigating with
BottomNavigation
, if you attempt to restore a back stack with multiple entries, theBottomMenuItem
is not correctly updated. (b/270447657) - When using Navigation with Fragments, after restoring the state the
NavBackStackEntry
Lifecycle
does not getDESTROYED
when its fragment isDESTROYED
. (b/270610768)
Version 2.6.0-alpha05
February 8, 2023
androidx.navigation:navigation-*:2.6.0-alpha05
is released. Version 2.6.0-alpha05 contains these commits.
New Features
NavController.popBackStack(route)
,NavController.getBackStackEntry(route)
,NavController.clearBackStack(route)
now all support routes with arguments partially or fully filled in. Note that the arguments have to be an exact match with the entry's arguments. (Iebd28, Ic678c, I3b37b, b/257514373)- The
FragmentNavigator
now uses the transition APIs when navigating and poppingNavBackStackEntries
. This means that theNavBackStackEntry
Lifecycle
will now wait for the entering and exiting fragment special effects to complete before moving their finalLifecycle.State
. (I3cb19, b/238686802) - The
DialogFragmentNavigator
now uses the transition APIs when navigating and poppingNavBackStackEntries
. This means that theNavBackStackEntry
Lifecycle
will now wait for theDialogFragment
Lifecycle
to move toDESTROYED
before moving toDESTROYED
itself. (I53ee5, b/261213893)
API Changes
NavigatorState
now provides theprepareForTransition
API to allowNavigator
s to moveNavBackStackEntries
to intermediateLifecycle.State
s. (I42c21, b/238686802)- You can now access the back stack associated with a
NavGraphNavigator
or aComposeNavigator
via abackstack
property.ComposeNavigator
also now exposes theonTransitionComplete()
callback to mark aNavBackStackEntry
that has executed a navigate orpopBackStack
operation as complete. (I02062, I718db, b/257519195)
Bug Fixes
- Navigator state will now no-op when using the
push/popWithTransition
APIs and the entry is already being handled. (Iadbfa, b/261213893) - When using
launchSingleTop
with a nestedNavGraph
all destinations starting from original destination to itsstartDestination
will only be properly added to the top of the backstack. (Id4bea, b/253256629) - Navigation will now properly replace the
DialogFragment
instance when navigating to the same destination with thelaunchSingleTop
flag set to true. (I45b5a, b/149572817) - Navigation SafeArgs will no longer cause a compilation error when using arguments that are exactly 19 characters long. (Id60bc, b/257110095)
Version 2.6.0-alpha04
November 9, 2022
androidx.navigation:navigation-*:2.6.0-alpha04
is released. Version 2.6.0-alpha04 contains these commits.
New Features
- Custom subclasses of
NavType
can now overrideserializeAsValue
to serialize a value into a String, allowing both serialization and deserialization (viaparseValue
) to be entirely encapsulated in theNavType
class.StringType
now overrides this method to callUri.encode
on the givenString
. (Ie5213, b/247637434) NavigationUI
now provides logs when it fails to navigate via a selectedMenuItem
. (I2af5a, b/247730357)
Bug Fixes
- Navigation deep links are now parsed lazily instead of on graph initialization which could improve app performance at start up. (Iab0ab)
- Fixed crash caused by navigating up after deep linking to a destination with null default arguments. (I51c24, b/243183636)
Dependency Update
- Navigation's support for Dynamic Feature Modules now depend on the granular Play Feature Delivery Library. (Ib4ddc)
- Navigation Safe Args now depends on Android Gradle Plugin version 7.3.0. This means it is now only compatible with versions 7.3.0+. (I47e49)
Version 2.6.0-alpha03
October 24, 2022
androidx.navigation:navigation-*:2.6.0-alpha03
is released. Version 2.6.0-alpha03 contains these commits.
Bug Fixes
- From Navigation
2.5.3
:NavHost
will no longer cause aNoSuchElementException
when there is no destination available for theCrossfade
to compose. It will now just skip the composition. (Ieb46e, b/253299416) - From Navigation
2.5.3
: Fixed an issue where saved Compose state (e.g., usages ofrememberSaveable
) were not being forgotten and removed when a destination was popped off the back stack. (I64949)
Dependency Updates
- Navigation now depends on Fragment
1.5.4
. (Icd424)
Version 2.6.0-alpha02
October 5, 2022
androidx.navigation:navigation-*:2.6.0-alpha02
is released. Version 2.6.0-alpha02 contains these commits.
Behavior Changes
- When passing the ID of a navigation graph to
AppBarConfiguration
(such as via aMenu
),NavigationUI
now only considers the start destination of that navigation graph as a top level destination, rather than incorrectly marking every destination within the graph as a top level destination. The behavior of passing the ID of an individual destination is unchanged. This same functionality is available to your own code via the newisTopLevelDestination
function onAppBarConfiguration
. (Ie936e, b/238496771)
Bug Fixes
- The
navigation:navigation-fragment
component now depends on Fragment version1.5.2
. (I00ba4) - The selected menu item will no longer be updated when navigating to a
FloatingWindow
destination such as a dialog. (I4cde8, b/240308330)
Version 2.6.0-alpha01
September 7, 2022
androidx.navigation:navigation-*:2.6.0-alpha01
is released. Version 2.6.0-alpha01 contains these commits.
New Features
- The
setupWithNavController
integrations inNavigationUI
for working with the top app bar will now parseR.string
values forReferenceType
arguments found in yourandroid:label
into their String values instead of outputting the auto-generated resource integer. (I5f803, b/167959935) NavDeepLink
now supports default values for arrays, which allows support for repeated query params that will map to the argument's array type.NavType
also now includes a default method which can be overridden to combine two parsed values. (Id68c3, b/209977108)- When using the exact string
${applicationId}
as the placeholder in theapp:data
andapp:dataPattern
attributes in the activity element of a navigation XML file, the placeholder will be automatically filled in with thepackageName
of the context upon inflation. (Iaabde, b/234223561) - Attempting to create an empty
NavDeepLink
using thenavDeepLink
Kotlin DSL will now result in a lint warning indicating that a deep link needs an uri, action, and/or mimetype to be valid. (I08d2f, b/154038883)
API Changes
- Added new
NavDestination
extension function to parse dynamic labels with arguments in the form ofandroid:label="{arg}"
into String. SupportsReferenceType
arguments by parsingR.string
values into their String values. (I07d89, b/236269380)
Behavior Changes
- NavBackStackEntry's
arguments
and thearguments
passed to anOnDestinationChangedListener
are now only a copy of the immutable arguments that were created when you navigated to the destination. This means any changes made to those Bundles will not be reflected in subsequent accesses to thearguments
or otherOnDestinationChangedListener
instances. (I676f5)
Bug Fixes
- From Navigation
2.5.2
: Dynamic Navigation now properly attempts to install Activity destinations from other modules before navigating to them. (Ia2c16, b/240292838) - From Navigation
2.5.2
: Navigation will now properly replace the Fragment instance when navigating to the same destination and setting thelaunchSingleTop
flag to true. (I5a2f1, b/237374580) - From Navigation
2.5.2
: FixedIllegalStateException
caused by navigating to a double nested graph that shares a parent with a new popped start destination. (I9f7cb, b/243778589)
Version 2.5
Version 2.5.3
October 24, 2022
androidx.navigation:navigation-*:2.5.3
is released. Version 2.5.3 contains these commits.
Bug Fixes
NavHost
will no longer cause aNoSuchElementException
when there is no destination available for theCrossfade
to compose. It will now just skip the composition. (Ieb46e, b/253299416)- Fixed an issue where saved Compose state (e.g., usages of
rememberSaveable
) were not being forgotten and removed when a destination was popped off the back stack. (I64949)
Version 2.5.2
September 7, 2022
androidx.navigation:navigation-*:2.5.2
is released. Version 2.5.2 contains these commits.
Bug Fixes
- Dynamic Navigation now properly attempts to install Activity destinations from other modules before navigating to them. (Ia2c16, b/240292838)
- Navigation will now properly replace the Fragment instance when navigating to the same destination and setting the
launchSingleTop
flag to true. (I5a2f1, b/237374580) - Fixed
IllegalStateException
caused by navigating to a double nested graph that shares a parent with a new popped start destination. (I9f7cb, b/243778589)
Dependency Update
- Navigation
2.5.2
now depends on Fragment1.5.2
. (aosp/2178734)
Version 2.5.1
July 27, 2022
androidx.navigation:navigation-*:2.5.1
is released. Version 2.5.1 contains these commits.
Bug Fixes
Navigation Safe Args
will no longer cause deprecation warnings in generated classes when using custom argument types that are saved in aBundle
. (Id86ed, b/237725966)
Dependency Updates
- The Navigation library now depends on Lifecycle
2.5.1
. (Ib4451) - The Navigation library now depends on Activity
1.5.1
. (I3efe8) - The Navigation library now depends on Fragment
1.5.1
. (I56177)
Version 2.5.0
June 29, 2022
androidx.navigation:navigation-*:2.5.0
is released. Version 2.5.0 contains these commits.
Important changes since 2.4.0
- CreationExtras Integration -
Navigation
now has the ability to provide a statelessViewModelProvider.Factory
via Lifecycle2.5.0
’sCreationExtras
.
Navigation SafeArgs
Navigation Safe Args
has upgraded theAndroid Gradle Plugin
dependency to rely on7.0.4
, dropping compatibility for AGP versions before7.0
.- Added support for the namespace build.gradle attribute to be used instead of applicationId.
Other Changes
- The
visibleEntries
API is no longer experimental and provides a function to retrieve all of the entries whose destination is currently visible according to theNavController
.
Version 2.5.0-rc02
June 15, 2022
androidx.navigation:navigation-*:2.5.0-rc02
is released. Version 2.5.0-rc02 contains these commits.
Bug Fixes
- Fixed a crash caused by fast switching between bottom destinations when using the Navigation Compose
NavHost
. (I3979a, b/234054916) Navigation SafeArgs
will no longer crash when using anapplicationIdSuffix
and namespace with either noapplicationId
present, or when theapplicationId
and namespace differ. (I754b1, b/233119646)NavArgument
now has a customtoString()
function to show the internal values of the argument. (I900a8)
Version 2.5.0-rc01
May 11, 2022
androidx.navigation:navigation-*:2.5.0-rc01
is released. Version 2.5.0-rc01 contains these commits.
New Features
- Added a new lint rule to warn against placing
<deeplink>
elements inside<activity>
elements in yournavigation.xml
file.(Ic15a5, b/178403185)
Bug Fixes
- Composable scopes in
NavHost
andDialogHost
are now disposed in the expected order, i.e. inner composabled are disposed before outer composables. (I157e6) - Navigation SafeArgs now uses
PathSensitivity.RELATIVE
in theArgumentsGenerationTask
to allow for cache relocatability. This means the cache entry can now be re-used from a CI build to a local build. (I5f67c, b/173420454) - The
UnrememberedGetBackStackEntryDetector
lint rule has been updated to ensure that theremember
call surrounding the call togetBackStackEntry()
also passes in aNavBackStackEntry
object as a key.(Ib7081, b/227382831)
Version 2.5.0-beta01
April 20, 2022
androidx.navigation:navigation-*:2.5.0-beta01
is released. Version 2.5.0-beta01 contains these commits.
Bug Fixes
DialogNavigator
now usespopWithTransition
when executing adismiss()
call. This fixes a race condition when using aViewModel
withindialog
destination that would cause anIllegalStateException
when dismissing the Dialog by either using system back or tapping outside of the dialog to exit. (Id7376, b/226552301)
Dependency Updates
- Navigation now depends on Lifecycle
2.5.0-beta01
, fixing anIllegalStateException
when nesting oneNavHost
within anotherNavHost
in a non-primary bottom navigation tab when using multiple back stacks.
Version 2.5.0-alpha04
April 6, 2022
androidx.navigation:navigation-*:2.5.0-alpha04
is released. Version 2.5.0-alpha04 contains these commits.
API Changes
visibleEntries
is no longer experimental. (I4829f, b/225394514)
Bug Fixes
- NavHost now depend on
visibleEntries
from theNavController
to determine which entries to compose. This means that when using nested NavHost the innerNavHost
should now properly animate out. (I4ba2b, b/225394514) - The
visibleEntries
StateFlow
provided byNavController
is now based on the entry max Lifecycle state instead of the current Lifecycle state. This means that even if the host lifecycle of thenavController
goes below STARTED, the list of visible entires will remain the same. (I9e2a8, b/225394514) SavedStateViewFactory
now supports usingCreationExtras
even when it was initialized with aSavedStateRegistryOwner
. If extras are provided, the initialized arguments are ignored. (I6c43b, b/224844583)NavDeepLink
can now parse Uris with a single query parameter with no value. (I0efe8, b/148905489)- Empty string are now considered as valid arguments in deep links. (I70a0d, b/217399862)
Navigation Safe Args
will no longer crash when using namespaces and noAndroidManifest.xml
is present. (I17ccf, b/227229815)
Version 2.5.0-alpha03
February 23, 2022
androidx.navigation:navigation-*:2.5.0-alpha03
is released. Version 2.5.0-alpha03 contains these commits.
API Changes
- You can now pass in
CreationExtras
toby navGraphViewModels
to create aViewModel
. (I29217, b/217618359)
Bug Fixes
NavDeepLinks
now properly support encoded new line characters embedded in routes/deep link URIs. (I513d1, b/217815060)CreationExtras
will now work correctly when used withNavBackStackEntries
to create ViewModels. (I69161, b/217617710)- Navigation Safe Args now supports using the namespace defined
in the
build.gradle
in place of the package in the AndroidManifest. (I659ef, b/217414933)
Version 2.5.0-alpha02
February 9, 2022
androidx.navigation:navigation-*:2.5.0-alpha02
is released. Version 2.5.0-alpha02 contains these commits.
Bug Fixes
- From Navigation
2.4.1
: TheNavHostFragment
will now properly set theOnBackPressedDispatcher
when using viewbinding with nested graphs. (Ifbb51, b/214577959) - From Navigation
2.4.1
: When deep linking through multiple nestedNavGraph
s the back stack will now properly include intermediate start destinations. (I504c0, b/214383060)
Version 2.5.0-alpha01
January 26, 2022
androidx.navigation:navigation-*:2.5.0-alpha01
is released. Version 2.5.0-alpha01 contains these commits.
New Features
NavBackStackEntry
now integrates with ViewModel CreationExtras, introduced as part of Lifecycle2.5.0-alpha01
. (Ib9fe2, b/207012490)
Bug Fixes
- Fixed an issue where accessing a
ViewModel
created viaby navGraphViewModels()
from a Fragment'sonCreate()
would fail with anIllegalStateException
. (I8a14d) NavDeepLink
s will no longer unnecessarily decode args twice, meaning that the proper args are now passed to your final destination. (I31b0a, b/210711399)
Safe Args
- Safe Args now depends on Android Gradle Plugin version 7.0.4. This means that Navigation Safe Args will no longer be compatible with Android Studio versions prior to 7.0, but is now compatible with Android Gradle Plugin 7.1.0 and higher. (I41c88, b/213086135, b/207670704)
Version 2.4.2
Version 2.4.2
April 6, 2022
androidx.navigation:navigation-*:2.4.2
is released. Version 2.4.2 contains these commits.
Bug Fixes
- Backported from Navigation
2.5.0-alpha03
:NavDeepLinks
now properly support encoded new line characters embedded in routes/deep link URIs. (I513d1, b/217815060) - Backported from Navigation
2.5.0-alpha03
: Navigation SafeArgs now supports using the namespace defined in thebuild.gradle
in place of the package in the AndroidManifest. (I659ef, b/217414933) - Backported from Navigation
2.5.0-alpha04
:Navigation Safe Args
will no longer crash when using namespaces and noAndroidManifest.xml
is present. (I17ccf, b/227229815) - Backported from Navigation
2.5.0-alpha04
: Empty string are now considered as valid arguments in deep links. (I70a0d, b/217399862)
Version 2.4.1
Version 2.4.1
February 9, 2022
androidx.navigation:navigation-*:2.4.1
is released. Version 2.4.1 contains these commits.
Bug Fixes
- The
NavHostFragment
will now properly set theOnBackPressedDispatcher
when using viewbinding with nested graphs. (Ifbb51, b/214577959) - When deep linking through multiple nested
NavGraph
s the back stack will now properly include intermediate start destinations. (I504c0, b/214383060) - Backported from Navigation
2.5.0-alpha01
: Fixed an issue where accessing a ViewModel created viaby navGraphViewModels()
from a Fragment'sonCreate()
would fail with anIllegalStateException
. (I8a14d) - Backported from Navigation
2.5.0-alpha01
:NavDeepLink
s no longer unnecessarily decode args twice, meaning that the properly decoded args are now passed to your final destination. (I31b0a, b/210711399) - Backported from Navigation
2.5.0-alpha01
: Safe Args now depends on Android Gradle Plugin version 7.0.4. This means that Navigation Safe Args will no longer be compatible with Android Studio versions prior to 7.0, but is now compatible with Android Gradle Plugin 7.1.0 and higher. (I41c88, b/213086135, b/207670704)
Version 2.4.0
Version 2.4.0
January 26, 2022
androidx.navigation:navigation-*:2.4.0
is released. Version 2.4.0 contains these commits.
Important changes since 2.3.0
- All Navigation artifacts have been rewritten in Kotlin. This has improved the nullability of classes using generics (such as
NavType
subclasses). All Kotlin extension functions that used to be part of the-ktx
artifacts have been moved to their respective main artifacts. The-ktx
artifacts will continue to be published, but are completely empty. - The
navigation-fragment
artifact now contains a prebuilt implementation of a two pane layout via the newAbstractListDetailFragment
. This fragment uses aSlidingPaneLayout
to manage a list pane (which your subclass provides) and a detail pane, which uses aNavHostFragment
as its implementation, as seen in our example implementation. - The
currentBackStackEntryAsFlow()
method onNavController
provides aFlow
that emits whenever the currentNavBackStackEntry
changes. This flow can be used as an alternative to manually managing anOnDestinationChangedListener
. - NavController now offers the ability to retrieve a list of all visible
NavBackStackEntry
instances as aStateFlow
via the experimentalvisibleEntries
property. - It is now possible to extend the
NavType
class to create custom NavTypes. Custom types are supported only when building your navigation graph programmatically, such as via the Navigation Graph Kotlin DSL. Navigation now provides
findStartDestination()
andgetHierarchy()
APIs that can be used to help implement custom NavigationUI.findStartDestination()
is an extension function onNavGraph
that will locate the actual start destination that will be displayed when you navigate to the graph, even if thestartDestination
is itself a nestedNavGraph
.getHierarchy()
is a function onNavDestination
that can be used to verify if a given destination is within the hierarchy of another.val matchingRoute: Boolean = destination.hierarchy.any { it.route == routeToFind }
NavigationUI
methods that took aBottomNavigationView
have been updated to instead take its superclass introduced in Material1.4.0
,NavigationBarView
. This allows these methods to be used with theNavigationRailView
.When inflating an
<action>
element via XML, animation attributes can use attributes pulled from your theme using theapp:enterAnim="?attr/transitionEnter"
syntax.Safe Args now generates a
fromSavedStateHandle()
method for eachNavArgs
class. (#122, b/136967621)class HomeViewModel(savedStateHandle: SavedStateHandle) : ViewModel() { // Create a HomeDestinationArgs class with type safe accessors for each argument // defined on your destination private val args = HomeDestinationArgs.fromSavedStateHandle(savedStateHandle) }
Navigation Routes and the Kotlin DSL
Previous versions of Navigation relied on each destination having a constant integer ID that would uniquely identify it from its sibling destinations and allow you to navigate()
to that destination either directly or via an action. While this continues to be valid and useful, particularly in cases where you are defining your navigation graph in XML and can use auto-generated R.id
constants or Safe Args (which uses those constants to generate code at build time), this system of unique integers did not capture the semantic meaning and expressiveness needed to support fully dynamic graphs built programmatically at runtime via the Navigation Kotlin DSL.
This release introduces a new option for uniquely identifying a destination in a navigation graph by its route. A route is a String
that defines the unique path to a destination. All Kotlin DSL methods that took a destination ID are now deprecated and replaced with an equivalent API that takes a route.
Each route should be treated as the ‘path’ part of a Uri
that defines that destination, e.g., home
, profile/{userId}
, profile/{userId}/friends
, etc. When the identity of a destination is associated with a specific piece of content, those dynamic arguments should be part of the route, following the same rules as implicit deep links.
All NavController
APIs that used to only take an ID now have an overload that takes a route String
. This includes navigate()
, popBackStack()
, popUpTo()
, and getBackStackEntry()
.
This has had some API implications:
- The
popUpTo
Kotlin property on the Kotlin DSL has been deprecated in favor ofpopUpToId
. - The
getStartDestination()
API has been deprecated in favor ofgetStartDestinationId()
.
Unlike when navigating by ID, navigating by route follows the same rules as implicit deep links in that you can directly navigate to any destination in any nested graph, ensuring that these routes are usable in multi-module projects without explicitly adding an externally visible deep link to each destination.
Navigation Compose
The navigation-compose
artifact provides integration between the Navigation Component and Jetpack Compose. It uses @Composable
functions as the destinations in your application.
This release provides:
- A
NavHost
composable that allows you to construct your navigation graph via a Kotlin DSL, usingcomposable
anddialog
destinations, plus support for optional Navigators such as those from Accompanist Navigation Material. - Mandatory support for crossfading between destinations. Accompanist Navigation Animation can be used to control the enter and exit transitions using experimental Compose APIs.
- Scoping of a
Lifecycle
to each composable destination. Each destination only reaches theRESUMED
state when any entering transitions finish and immediately drops toSTARTED
when any exiting transitions start, thus allowing you to avoid allIllegalStateException
and multi-touch issues by only triggering anavigate
call when theLifecycle
isRESUMED
. - Scoping of
ViewModel
(via theviewModel()
API of Lifecycle ViewModel Compose2.4.0
orhiltViewModel()
of Hilt Navigation Compose1.0.0
at the destination level, providing a scope that survives configuration changes and being on the back stack (when your Composable content is otherwise disposed) and a signal in the ViewModel’sonCleared()
that indicates the permanent disposal and cleaning up of state associated with thatNavBackStackEntry
. - Scoping of
rememberSaveable
state at a destination level, ensuring that all composable state is saved and restored automatically when you return to a destination. - Full support for saving and restoring the state of the
NavController
and its destination’s state after process death and recreation. - Automatic integration with the system back button.
Support for passing arguments, attaching deep links to destinations, and returning a result to previous destinations.
Compose specific helpers in
rememberNavController()
andcurrentBackStackEntryAsState()
to allow hoisting state and connecting theNavController
to composables outside of theNavHost
(such as a bottom navigation bar).
val navController = rememberNavController()
Scaffold { innerPadding ->
NavHost(navController, "home", Modifier.padding(innerPadding)) {
composable("home") {
// This content fills the area provided to the NavHost
HomeScreen()
}
dialog("detail_dialog") {
// This content will be automatically added to a Dialog() composable
// and appear above the HomeScreen or other composable destinations
DetailDialogContent()
}
}
}
See the Compose Navigation guide for more information.
Multiple back stacks
The NavController is responsible for managing the back stack of destinations, adding destinations to the back stack when you navigate()
to them and removing them when you call popBackStack()
or trigger the system back button. The existing NavOptions
class and the integration into <action>
elements in the navigation graph XML has been expanded to support saving and restoring the back stack.
As part of this change, the NavigationUI
methods of onNavDestinationSelected()
, BottomNavigationView.setupWithNavController()
and NavigationView.setupWithNavController()
now automatically save and restore the state of popped destinations, enabling support for multiple back stacks without any code changes. When using Navigation with Fragments, this is the recommended way to integrate with multiple back stacks.
The underlying APIs for saving and restoring the state are exposed via a number of surfaces:
In Navigation XML, the
<action>
element can now use the boolean attributes ofapp:popUpToSaveState
andapp:restoreState
to save the state of any destinations popped viaapp:popUpTo
and restore the state associated with the destination passed as theapp:destination
:<action android:id=”@+id/swap_stack” app:destination=”@id/second_stack” app:restoreState=”true” app:popUpTo=”@id/first_stack_start_destination” app:popUpToSaveState=”true” />
In the
navOptions
Kotlin DSL, you can add therestoreState
boolean property and thesaveState
boolean property on thepopUpTo
builder:// Use the navigate() method that takes a navOptions DSL Builder navController.navigate(selectedBottomNavRoute) { launchSingleTop = true restoreState = true popUpTo(navController.graph.findStartDestination().id) { saveState = true } }
In manually building a
NavOptions
object via theNavOptions.Builder
, you can use thesetRestoreState()
and new overload tosetPopUpTo()
that takes an additionalsaveState
parameter.NavOptions navOptions = new NavOptions.Builder() .setLaunchSingleTop(true) .setRestoreState(true) .setPopUpTo(NavGraph.findStartDestination(navController.getGraph()).getId(), false, // inclusive true) // saveState .build(); navController.navigate(selectedBottomNavId, null, navOptions);
Programmatic calls to
popBackStack()
can now include an additionalsaveState
parameter.You can use the
clearBackStack()
method to clear any state that was saved withpopBackStack()
orpopUpToSaveState
.
In all cases, the NavController
will save and restore the state of each NavBackStackEntry
, including any navigation destination scoped ViewModel
instances. The Navigator
APIs have been updated to enable each Navigator
to support saving and restoring their own state.
Behavior changes
NavDeepLinkBuilder
now addsPendingIntent.FLAG_IMMUTABLE
to thePendingIntent
returned bycreatePendingIntent()
, ensuring that this API works as expected when targeting Android 12.- Navigation now depends on
Lifecycle
2.3.1
and now markssetGraph()
,popBackStack()
,navigateUp()
, andnavigate()
, the methods that update theNavBackStackEntry
Lifecycle
, as@MainThread
, aligning Navigation with the main thread enforcement introduced in Lifecycle2.3.0
. - Deep links now verify that all required arguments (those without default values) are present in the
Uri
. NavDeepLink
parsed arguments now consider pound signs in the same way as question marks as a separator between path segments, preventing an argument from spanning across the pound sign.- When generating actions, Kotlin code generated from Safe Args now puts arguments without default values before those with default values as parameters.
- When generating arguments, Safe Args now puts parameters without default values before those with default values.
- Safe-Args now depends on Android Gradle Plugin 4.2.0. This means you should no longer get the using
applicationIdTextResource
warning.
Known issues
- Fixed in Navigation
2.5.0-alpha01
: accessing aViewModel
created viaby navGraphViewModels()
from a Fragment'sonCreate()
will fail with anIllegalStateException
. (b/213504272) - Fixed in Navigation
2.5.0-alpha01
: Safe Args 2.4.0 is incompatible with Android Gradle Plugin 7.1.0 and higher. (b/213086135) - Deep linking with multiple nested nav graphs doesn't correctly create the full backstack. (b/214383060)
Version 2.4.0-rc01
December 15, 2021
androidx.navigation:navigation-*:2.4.0-rc01
is released. Version 2.4.0-rc01 contains these commits.
Behavior changes
NavDeepLink
parsed arguments now consider pound signs in the same way as question marks as a separator between arguments. (I21309, b/180042703)
Bug Fixes
- Deeplinks will no longer ignore arguments with values that are the same as the name of the placeholder. (If8017, b/207389470)
NavController
will no longer crash when popping a nested destination using transitions after theNavController
has been restored. (I0f7c9, b/205021623)- The error message when using an invalid
startDestination
will now default to the start destination's route if one is available. (I86b9d, b/208041894)
Navigation Compose Bug Fixes
- Fixed potential crash caused by fast switching between the start destination and another destination using bottom nav menu items. (Ic8976, b/208887901)
- Dialog destination are now properly restored on top of the screen after config changes or process death. (I4c0dc, b/207386169)
- Fixed an issue where attempting to retrieve a
ViewModel
from a dialog’sNavBackStackEntry
would fail when the dialog was dismissed. (I6b96d, b/206465487) - Fixed an issue when using
activity
destinations with Navigation Compose'sNavHost
that would result in infinite recompositions. (I8f64c) - Fixed a leak in Navigation Compose where it was holding on to a reference of the old activity after a config change or process death. (I4efcb, b/204905432)
Safe Args Bug Fixes
SafeArgs
no longer crashes when attempting to restore custom parcelable arrays after process death. (I618e8, b/207315994)- Fixed a bug in safe args that would not allow boolean arrays to have a
null
value. (I8c396, b/174787525)
Version 2.4.0-beta02
November 3, 2021
androidx.navigation:navigation-*:2.4.0-beta02
is released. Version 2.4.0-beta02 contains these commits.
API Changes
- The handling of both explicit and implicit
deep links now automatically adds the
saveState
flag when navigating to another graph, ensuring that code such asNavigationUI.setupWithNavController
and code using multiple back stacks works as expected. (Ic8807)
Behavior Changes
- Deep link patterns are now compiled lazily in NavDeepLink instead of during inflation. This should improve the inflation time of navigation graphs that include deep links. (b8d257, b/184149935)
Bug Fixes
- Fixed an issue where NavBackStackEntries were being pushed down to
Lifecycle.State.CREATED
after moving toLifecycle.State.STARTED
when theNavHost
is added directly to the activity'ssetContent()
. (Ia5ac1, b/203536683) - Fixed a race condition where
popping a
DialogFragment
destination off of the back stack before the dialog was actually shown would not actually dismiss the dialog, resulting in a crash when the errant dialog was manually dismissed by the user. (I687e5) - Fixed an issue where the
onNavDestinationSelected
API onNavigationUI
would returntrue
even if you didn't actuallynavigate()
to that navigation graph. It now uses the same logic used internally bysetupWithNavController
to only select theMenuItem
associated with the current destination using thehierarchy
of the destination. (I2b053)
Version 2.4.0-beta01
October 27, 2021
androidx.navigation:navigation-*:2.4.0-beta01
is released. Version 2.4.0-beta01 contains these commits.
New Features
- You can now use
by navGraphViewModel
with a route as an alternative to using an ID so as to better support using the Navigation Kotlin DSL with Fragments. (I901e3, b/201446416)
API Changes
- The
visibleEntries
API is now experimental. (I93f6f)
Bug Fixes
- ViewModels will no longer be destroyed when transitions are interrupted by navigating back and forth between the same screens (Id52d8, b/200817333)
- Nullable
NavDeepLink
arguments no longer require a default value when adding deep links toNavDestination
s. (I5aad4, b/201320030) - NavBackStackEntries now with different Lifecycles are not longer considered equal. This means NavHost will properly recompose all destinations when doing navigation with singleTop and when reselecting bottom menu items. (I1b351, b/196997433)
- Fixed an issue with
AbstractListDetailFragment
that caused thelayout_width
andlayout_weight
attributes on the list pane returned byonCreateListPaneView()
to be incorrectly handled or ignored. (f5fbf3) - The visual state of dialog destinations now
correctly stays in sync with the
DialogFragmentNavigator
's state. This means that manually calling the asynchronousdismiss()
API forDialogFragment
now properly clears all dialog destinations above the now dismissed dialog. This does not affect cases where you usepopUpTo
orpopBackStack()
to dismiss your dialog. (I77ba2) AbstractAppBarOnDestinationChangedListener
now has clearer error messaging foronDestinationChanged()
. (Ie742d)
Version 2.4.0-alpha10
September 29, 2021
androidx.navigation:navigation-*:2.4.0-alpha10
is released. Version 2.4.0-alpha10 contains these commits.
New Features
- NavController now offers the ability to retrieve a list of all visible
NavBackStackEntry
instances via thevisibleEntries
StateFlow (Ia964e) rememberNavController()
now takes a optional set ofNavigator
instances that will be added to the returnedNavController
to better support optional Navigators such as those from Accompanist Navigation Material. (I4619e)
Bug Fixes
- Dynamic Navigation will no longer crash when the Activity is recreated. (Ifa6a3, b/197942869)
- Fixed an issue with the system back button that occurs only after popping back to a composable destination that contains a
NavHost
. (3ed148, b/195668143) - SafeArgs now generates the arguments for
fromBundle()
andfromSavedStateHandle()
in the proper parameter order. (I824a8, b/200059831)
Version 2.4.0-alpha09
September 15, 2021
androidx.navigation:navigation-*:2.4.0-alpha09
is released. Version 2.4.0-alpha09 contains these commits.
New Features
- You can now use the
clearBackStack()
method to clear any state that was saved withpopBackStack()
orpopUpToSaveState
. (I80a0f) - You can now pass in a list of arguments and/or deep links to your nested navigation graph's builder and they will automatically be added to the resulting graph. (I8a470, b/182545357)
API Changes
- The
navArgument
Kotlin DSL function is now part ofnavigation-common
instead ofnavigation-compose
. This will require updating imports to continue to use this function. (I1d095)
Behavior Changes
- When generating arguments, Safe Args now puts parameters without default values before those with default values. (I89709, b/198493585)
Bug Fixes
- When using Navigation Compose, NavGraphs will only be
DESTROYED
once all their children areDESTROYED
. (I86552, b/198741720) - Nullable
NavDeepLink
arguments no longer require a default value. (Ia14ef, b/198689811) - Calling
setGraph()
with a new graph will now also clear any saved back stacks in addition to its previous behavior of popping the back stack. (I97f96) - Fixed an issue where
OnDestinationChangedListener
instances and thecurrentBackStackEntryFlow
were not notified when usinglaunchSingleTop
. (Iaaebc)
Dependency Updates
- Navigation Compose now depends on Activity Compose 1.3.1. (I05829)
- Navigation Compose now depends on
Lifecycle ViewModel Compose
2.4.0-beta01
. (Ib86a3)
Version 2.4.0-alpha08
September 1, 2021
androidx.navigation:navigation-*:2.4.0-alpha08
is released. Version 2.4.0-alpha08 contains these commits.
New Features
- It is now possible to extend the
NavType
class to create custom NavTypes. Custom types are supported only when building your navigation graph programmatically, such as via the Navigation Graph Kotlin DSL. (I78440, b/196871885)
Behavior Changes
- When generating actions, Kotlin code generated from Safe Args now puts arguments without default values before those with default values as parameters. (Idb697, b/188855904)
- Deep links now verify that all required arguments (those without default values) are present in the
Uri
. (#204, b/185527157)
Bug Fixes
- Using
getBackStackEntry
andpreviousBackStackEntry
inside composable(), in conjunction withremember()
, will no longer cause an exception for no destination being on the back stack. (I75138, b/194313238) - Navigation Compose now properly recomposes when changing back
stack arguments and using
launchSingleTop=true
. (Iebd69, b/186392337) - There will no longer be an
ArrayIndexOutOfBoundsException
when callingsetGraph
with a graph with 13 or 29 destinations. (I1a9f1, b/195171984) - The SafeArgs java generator should no longer cause lint warnings when generating Args classes. (I1a666, b/185843837)
External Contribution
- Thanks ospixd for ensuring that deep links verify that all required arguments (those without default values) are present in the
Uri
. (#204, b/185527157)
Version 2.4.0-alpha07
August 18, 2021
androidx.navigation:navigation-*:2.4.0-alpha07
is released. Version 2.4.0-alpha07 contains these commits.
Bug Fixes
- Navigation Compose now properly saves state after configuration changes and when changing graphs while using the multiple back stack feature. (If5a3d, b/195141957)
- Re-selecting the same tab when using navigation compose with multiple back stacks will no longer result in a blank screen. (I860dc, b/194925622)
NavHost
now observes for changes in theLifecycle.State
ofNavBackStackEntry
s which means using aNavHost
in a fragment now will properly be recomposed as the lifecycle changes instead of resulting in a blank screen. (I4eb85, b/195864489)- Fixed an issue where dismissing a
DialogFragment
would not correctly update theNavController
state after recreating your activity (i.e., after a configuration change). (Icd72b) - Fixed an issue where popping a dialog destination would not update the NavController's system back button handling, potentially causing the NavController to intercept the back button even though it does not have any back stack to pop. (If3b34)
- Safe-args now automatically generates a
toSavedStateHandle
method for arguments which can be used to test yourViewModel
code. (If1e2d, b/193353880)
Version 2.4.0-alpha06
August 4, 2021
androidx.navigation:navigation-*:2.4.0-alpha06
is released. Version 2.4.0-alpha06 contains these commits.
API Changes
- The
requireSlidingPaneLayout()
andrequireDetailPaneNavHostFragment()
methods onAbstractListDetailFragment
have been renamed togetSlidingPaneLayout()
andgetDetailPaneNavHostFragment()
, respectively. (I34a08)
Behavior Changes
- When navigating with animations (like
Crossfade
), the new destination’sLifecycle
will now only reach theRESUMED
when the animation completes. (If0543, b/172112072, b/194301889) - Navigation Compose's
NavHost
now sets the graph as part of the first composition. (Ieb7be)
Bug Fixes
- Popping the last destination of a navigation graph no longer throws a
ClassCastException
. (If0543, b/172112072, b/194301889) - Fixed a
NullPointerException
that would occur when adding a deep link without aUri
and navigating via a route or deep link. (938a0c, b/193805425) - Fixed an issue in Navigation Compose where
a deep linked
NavBackStackEntry
would not reach theRESUMED
state. (I192c5) - Fixed an issue where popping a dialog destination would not update the NavController's system back button handling, potentially causing the NavController to intercept the back button even though it does not have any back stack to pop. (aosp/1782668)
Version 2.4.0-alpha05
July 21, 2021
androidx.navigation:navigation-*:2.4.0-alpha05
is released. Version 2.4.0-alpha05 contains these commits.
Behavior Changes
- Navigation Compose’s
NavHost
now always uses Crossfades when navigating through destinations. (I07049, b/172112072) - You can now make changes to the graph of a NavHost. Graphs
with the same startDestination and destinations in the graph will be
considered equal and will not clear the
NavController
back stack. (I0b8db, b/175392262)
Bug Fixes
- Fixed a
NoSuchElementException
when callingpopBackStack()
from within aLifecycleObserver
attached to aNavBackStackEntry
caused by reentrant updates to the NavController's state. (I64621) AbstractListDetailFragment
now allowsSlidingPaneLayout
to be completely stripped from your APK whenAbstractListDetailFragment
is not used. (I611ad)NavGraph
andNavDestination
now override the equals method so two objects with the same values will be considered equal. (I166eb, b/175392262)
Version 2.4.0-alpha04
July 1, 2021
androidx.navigation:navigation-*:2.4.0-alpha04
is released. Version 2.4.0-alpha04 contains these commits.
New Features
- The
navigation-fragment
artifact now contains a prebuilt implementation of a two pane layout via the newAbstractListDetailFragment
. This fragment uses aSlidingPaneLayout
to manage a list pane (which your subclass provides) and a detail pane, which uses aNavHostFragment
as its implementation, as seen in our example implementation. (Iac4be, b/191276636) - The
NavHost
of thenavigation-compose
artifact now supportsdialog
destinations in addition tocomposable
destinations. These dialog destinations will each be shown within a ComposableDialog
, floating above the currentcomposable
destination. (I011d0)
val navController = rememberNavController()
Scaffold { innerPadding ->
NavHost(navController, "home", Modifier.padding(innerPadding)) {
composable("home") {
// This content fills the area provided to the NavHost
HomeScreen()
}
dialog("detail_dialog") {
// This content will be automatically added to a Dialog() composable
// and appear above the HomeScreen or other composable destinations
DetailDialogContent()
}
}
}
API Changes
- The
add
function inNavigatorState
has been renamed topush
. All current calls toadd()
will need to be changed to push(). (Ie89fc, b/172112072) - Custom
Navigator
instances can now use thepushWithTransaction
andpopWithTransition
APIs onNavigatorState
to push or pop a destination asynchronously. Note that this APIs are not yet used by any of the included navigators. (Ic4d7c, b/172112072)
Behavior Changes
NavDeepLinkBuilder
now addsPendingIntent.FLAG_IMMUTABLE
to thePendingIntent
returned bycreatePendingIntent()
, ensuring that this API works as expected when targeting Android 12. (If8c52)
Bug Fixes
- Fixed an issue with
<include-dynamic>
where arguments passed to the graph would not be correctly passed to the dynamically included graph. (I3e115) - Fixed a
NullPointerException
when navigating to a destination using astring[]
argument with a default value of@null
. (I1fbe8) - Add ProGuard rules for
@Navigator.Name
, fixing issues when using R8 3.1 full mode. (I2add9, b/191654433) - SafeArgs will no longer fail when building your app with
Kotlin
versions before1.5.0
. (Icd1ff, b/190739257)
Version 2.4.0-alpha03
June 16, 2021
androidx.navigation:navigation-*:2.4.0-alpha03
is released. Version 2.4.0-alpha03 contains these commits.
Bug Fixes
- Fixed an issue where two
navigate()
calls were needed to navigate to an included dynamic graph. (I7785c, b/188859835) - Fixed a regression introduced in
Navigation
2.4.0-alpha01
wheresetupActionBarWithNavController()
would not properly remove the Up icon when you are on a top level destination. (I5d443, b/189868637) - Fixed an
IllegalStateException
when callingpopBackStack()
after previously popping the root graph of the NavController. (I2a330, b/190265699) - ProGuard rules for
by navArgs()
now properly apply when usingnavigation-common
or any artifacts that depend on it. (I68800, b/190082521) - An
OnDestinationChangedListener
that callsnavigate()
the first time it receives a callback now properly get a second callback with the destination it navigated to. (Ie5f9e, b/190228815) - Safe Args no longer crashes when using it with dynamic feature modules and AGP 7.0+. (I69518, b/189966576)
Known Issue
- Safe Args will fail with an
Unable to find method ‘’java.lang.String kotlin.text.CarsKt.titleCase(char, java.util.Locale)’’
error when using Gradle6.7.0
due to a dependency on an older version of Kotlin. This can be worked around by updating to use Gradle 7.0. (b/190739257)
Version 2.4.0-alpha02
June 2, 2021
androidx.navigation:navigation-*:2.4.0-alpha02
is released. Version 2.4.0-alpha02 contains these commits.
New Features
- Routes are now supported for Activity, Fragment and Dialog destinations, as well as throughout the DynamicNavigation Kotlin DSL. (Ib5544, Ia617b, I22f96, b/188914648, b/188901565)
NavigationUI
has temporarily added experimental APIs to allow opting out of saving your state. While always saving the state is the correct behavior, there are still uses of deprecated libraries (i.e. retained fragments), that cannot be supported when saving the state so this gives an opportunity for apps to slowly convert away from any unsupported APIs. (Idf93c)Navigation now provides
findDestination()
andgetHierarchy()
APIs that can be used to help implement custom NavigationUI.findDestination()
is an extension function onNavGraph
that will locate a destination within the graph.getHierarchy()
is a function onNavDestination
that can be used to verify if a given destination is within the hierarchy of another.(I2932f, b/188183365)val matchingRoute: Boolean = destination.hierarchy.any { it.route == routeToFind }
NavigationUI methods that took a
BottomNavigationView
have been updated to instead take its superclass introduced in Material1.4.0
,NavigationBarView
. This allows these methods to be used with theNavigationRailView
. (Ib0b36, b/182938895)When inflating an
<action>
element via XML, animation attributes can use attributes pulled from your theme using theapp:enterAnim="?attr/transitionEnter"
syntax. (I07bc1, b/178291654)
API Changes
- Kotlin DSL builders that use an ID have been deprecated and should be replaced with builders that use routes (I85b42, b/188816479) (I9f58f, b/188816479)
Bug Fixes
DialogFragmentNavigator
now uses theNavigatorState.pop()
API to inform theNavController
when a dialog is dismissed by hitting the system back button or clicking outside of it, ensuring that theNavController
state is always in sync with the Navigator's state. (I2ead9)Navigation no longer gives a
ConcurrentModificationException
when using manipulating the list ofOnDestinationChangedListeners
from with anonDestinationChanged
callback. (Ib1707, b/188860458)Safe Args no longer crashes when attempting to generate direction properties in Kotlin. (Id2416, b/188564435)
The setId method on NavDestination is now properly annotated with
@IdRes
, so it only accepts resource ids. (I69b80)The int parameter of
findNode
is nowresId
instead ofresid
. (I7711d)
Dependency Update
- Safe-Args now depends on Android Gradle Plugin 4.2.0. This means you should no longer get the using
applicationIdTextResource
warning. (I6d67b, b/172824579)
Version 2.4.0-alpha01
May 18, 2021
androidx.navigation:navigation-*:2.4.0-alpha01
is released. Version 2.4.0-alpha01 contains these commits.
New Features
- The
currentBackStackEntryAsFlow()
method onNavController
provides aFlow
that emits whenever the currentNavBackStackEntry
changes. This flow can be used as an alternative to manually managing anOnDestinationChangedListener
. (I19c4a, #89, b/163947280)
Multiple back stacks
The NavController is responsible for managing the back stack of destinations, adding destinations to the back stack when you navigate()
to them and removing them when you call popBackStack()
or trigger the system back button. The existing NavOptions
class and the integration into <action>
entries in the navigation graph XML has been expanded to support saving and restoring the back stack. (b/80029773)
As part of this change, the NavigationUI
methods of onNavDestinationSelected()
, BottomNavigationView.setupWithNavController()
and NavigationView.setupWithNavController()
now automatically save and restore the state of popped destinations, enabling support for multiple back stacks without any code changes. When using Navigation with Fragments, this is the recommended way to integrate with multiple back stacks. (Ie07ca)
The underlying APIs for saving and restoring the state are exposed via a number of surfaces:
In Navigation XML, the
<action>
element can now use the boolean attributes ofapp:popUpToSaveState
andapp:restoreState
to save the state of any destinations popped viaapp:popUpTo
and restore the state associated with the destination passed as theapp:destination
:<action android:id=”@+id/swap_stack” app:destination=”@id/second_stack” app:restoreState=”true” app:popUpTo=”@id/first_stack_start_destination” app:popUpToSaveState=”true” />
In the
navOptions
Kotlin DSL, you can add therestoreState
boolean property and thesaveState
boolean property on thepopUpTo
builder:// Use the navigate() method that takes a navOptions DSL Builder navController.navigate(selectedBottomNavRoute) { launchSingleTop = true restoreState = true popUpTo(navController.graph.startDestinationId) { saveState = true } }
In manually building a
NavOptions
object via theNavOptions.Builder
, you can use thesetRestoreState()
and new overload tosetPopUpTo()
that takes an additionalsaveState
parameter.NavOptions navOptions = new NavOptions.Builder() .setLaunchSingleTop(true) .setRestoreState(true) .setPopUpTo(navController.getGraph().getStartDestinationId(), false, // inclusive true) // saveState .build(); navController.navigate(selectedBottomNavId, null, navOptions);
Programmatic calls to
popBackStack()
can now include an additionalsaveState
parameter.
In all cases, the NavController
will save and restore the state of each NavBackStackEntry
, including any navigation destination scoped ViewModel
instances. The Navigator
APIs have been updated to enable each Navigator
to support saving and restoring their own state.
The ComposeNavigator
used for composable
destinations in Navigation Compose and the FragmentNavigator
and DynamicFragmentNavigator
used for <fragment>
destinations in Navigation with Fragments have both been updated to use the new Navigator APIs and support saving and restoring state.
Navigation Routes
A route is a String
that uniquely identifies a destination. While previously only used in Navigation Compose, this concept has now graduated to become a part of the core Navigation APIs. This provides an alternative to using integer IDs when constructing your graph through the Navigation Kotlin DSL. (b/172823546)
All APIs that used to only take an ID now have an overload that takes a route String
. This includes navigate()
, popBackStack()
, popUpTo()
, and getBackStackEntry()
.
This has had some API implications:
- The
popUpTo
kotlin property on the Kotlin DSL has been deprecated in favor ofpopUpToId
. (I59c73, b/172823546) - The
getStartDestination()
API has been deprecated in favor ofgetStartDestinationId()
. (I0887f, b/172823546)
For developers upgrading from previous versions of Navigation Compose to Navigation Compose 2.4.0-alpha01
, this means that the following imports on extension methods are no longer necessary and should be removed:
import androidx.navigation.compose.navigation
import androidx.navigation.compose.createGraph
import androidx.navigation.compose.getBackStackEntry
import androidx.navigation.compose.navigate
import androidx.navigation.compose.popUpTo
The KEY_ROUTE
argument has been replaced with the route
property on NavDestination
, allowing you to call navBackStackEntry.destination.route
directly.
API Changes
- All Navigation artifacts have been rewritten in Kotlin. This has improved the nullability of classes using generics (such as
NavType
subclasses). All Kotlin extension functions that used to be part of the-ktx
artifacts have been moved to their respective main artifacts. The-ktx
artifacts will continue to be published, but are completely empty. (b/184292145) NavDeepLinkBuilder
now supports adding multiple distinct destinations to the generated back stack. (I3ee0d, b/147913689)- Add factory functions for
DynamicNavHostFragment
(Icd515, b/175222619) - The unique ID of a
NavBackStackEntry
is now exposed as part of its public API. (Ie033a) - The
name
andargument
fields and destructuring functions ofNamedNavArgument
are now public. (#174, b/181320559) - Introduced a new
NavBackStackEntry#provideToCompositionLocals
extension that provides theNavBackStackEntry
to the relevant composition locals. (#175, b/187229439)
Safe Args
Safe Args now generates a
fromSavedStateHandle()
method for eachNavArgs
class. (#122, b/136967621)class HomeViewModel(savedStateHandle: SavedStateHandle) : ViewModel() { // Create a HomeDestinationArgs class with type safe accessors for each argument // defined on your destination private val args = HomeDestinationArgs.fromSavedStateHandle(savedStateHandle) }
Updated Safe Args to depend on KotlinPoet
1.8.0
. (#172, b/183990444)
Behavior Changes
- Navigation now depends on
Lifecycle
2.3.1
and now markssetGraph()
,popBackStack()
,navigateUp()
, andnavigate()
, the methods that update theNavBackStackEntry
Lifecycle
, as@MainThread
, aligning Navigation with the main thread enforcement introduced in Lifecycle2.3.0
. (b/171125856) - Parsing Enum arguments from deep links is now case insensitive, allowing a deep link like
http://www.example.com/red
to match awww.example.com/{color}
deep link even when the enum has the value ofRED
. (#152, b/135857840)
Compose Compatibility
androidx.navigation:navigation-compose:2.4.0-alpha01
is only compatible with Compose version1.0.0-beta07
and above.
Bug Fixes
- Fixed an issue where trailing argument placeholders would take precedence over deep links that have a matching exact suffix. (#153, b/184072811)
NavHostFragment
now supports custom Navigators that use the same@Navigator.Name("dialog")
as the defaultDialogFragmentNavigator
. (Ib1c2c, b/175979140)- Improved the behavior of
NavigatorProvider#addNavigator
to ensure that calling it repeatedly with the same instance does not cause issues. (#176, b/187443146)
External Contributions
- Thanks simonschiller for building support for Safe Args generating a
fromSavedStateHandle()
method for eachNavArgs
class. (#122, b/136967621) - Thanks Bradleycorn for making parsing Enum arguments from deep links case insensitive. (#152, b/135857840)
- Thanks osipxd for fixing an issue where trailing argument placeholders would take precedence over deep links that have a matching exact suffix. (#153, b/184072811)
- Thanks tatocaster for updating Safe Args to depend on KotlinPoet
1.8.0
. (#172, b/183990444) - Thanks jossiwolf for making the
name
andargument
fields and destructuring functions ofNamedNavArgument
public. (#174, b/181320559) - Thanks jossiwolf for introducing a new
NavBackStackEntry#provideToCompositionLocals
extension that provides theNavBackStackEntry
to the relevant composition locals. (#175, b/187229439) - Thanks jossiwolf for improved the behavior of
NavigatorProvider#addNavigator
to ensure that calling it repeatedly with the same instance does not cause issues. (#176, b/187443146)
Navigation Compose Version 1.0.0
Version 1.0.0-alpha10
April 7, 2021
androidx.navigation:navigation-compose:1.0.0-alpha10
is released. Version 1.0.0-alpha10 contains these commits.
API Changes
NavHost
now accepts aModifier
, which is passed down to the composable container that wraps the destination composables. (I85aca, b/175125483)
Bug Fixes
NavHost
now works even when anOnBackPressedDispatcherOwner
is not found, such is the case when previewing theNavHost
. (I7d8b4)- Navigation Compose now depends on Navigation
2.3.5
, fixing an issue when usingBackHandler
inside aNavHost
destination. (I7e63b, b/182284739)
Version 1.0.0-alpha09
March 10, 2021
androidx.navigation:navigation-compose:1.0.0-alpha09
is released. Version 1.0.0-alpha09 contains these commits.
API Changes
LocalViewModelStoreOwner.current
now returns a nullableViewModelStoreOwner
to better determine whether aViewModelStoreOwner
is available in the current composition. APIs that require aViewModelStoreOwner
, such asviewModel()
andNavHost
, still throw an exception if aViewModelStoreOwner
is not set. (Idf39a)
Bug Fixes
- Navigation Compose now depends on Navigation 2.3.4 which includes the fix for attempting to set the same ViewModelStore object after the graph has been set. (I65c24, b/177825470)
Version 1.0.0-alpha08
February 24, 2021
androidx.navigation:navigation-compose:1.0.0-alpha08
is released. Version 1.0.0-alpha08 contains these commits.
New Features
NavHost
now populates theLocalSavedStateRegistryOwner
CompositionLocal with that destination’sNavBackStackEntry
, ensuring that any state directly saved into theSavedStateRegistry
will be saved and restored alongside the destination. (I435d7, b/179469431)
Version 1.0.0-alpha07
February 10, 2021
androidx.navigation:navigation-compose:1.0.0-alpha07
is released. Version 1.0.0-alpha07 contains these commits.
Dependency Updates
- Navigation Compose now depends on Lifecycle ViewModel Compose 1.0.0-alpha01 to provide
viewModel()
support tocomposable
destinations. (I7a374) NavHost
now uses the newLocalOnBackPressedDispatcherOwner
from Activity-Compose 1.3.0-alpha01 to get theOnBackPressedDispatcher
that is set on theNavController
. (I65b12)
Version 1.0.0-alpha06
January 28, 2021
androidx.navigation:navigation-compose:1.0.0-alpha06
is released. Version 1.0.0-alpha06 contains these commits.
API Changes
- Added a
getBackStackEntry(route: String)
extension method onNavController
that returns the associatedNavBackStackEntry
. (If8931)
Version 1.0.0-alpha05
January 13, 2021
androidx.navigation:navigation-compose:1.0.0-alpha05
is released. Version 1.0.0-alpha05 contains these commits.
Updated to depend on Compose 1.0.0-alpha10.
Version 1.0.0-alpha04
December 16, 2020
androidx.navigation:navigation-compose:1.0.0-alpha04
is released. Version 1.0.0-alpha04 contains these commits.
- Updated for compatibility with Compose
1.0.0-alpha09
.
Version 1.0.0-alpha03
December 2, 2020
androidx.navigation:navigation-compose:1.0.0-alpha03
is released. Version 1.0.0-alpha03 contains these commits.
Bug Fixes
- Fixed an issue where
popBackStack()
andnavigateUp()
would not work after a configuration change or process death and recreation. (Icea47, b/173281473) - Navigating to a nested graph within your NavHost now works properly. (I0948d, b/173647694)
Version 1.0.0-alpha02
November 11, 2020
androidx.navigation:navigation-compose:1.0.0-alpha02
is released. Version 1.0.0-alpha02 contains these commits.
API Changes
- Navigation compose now support NavOptions for using popUpTo and launchSingleTop operations (If96c3, b/171468994)
- Added a navigation function that takes a route instead of an ID that allows you to construct nested graphs in the Navigation Compose DSL. (I1661d)
- startDestination now comes before the route in the list of a parameters for a NavHost (Ie620e)
- You can now create a graph using the route as a start destination outside of a NavHost composable. (Iceb75)
Version 1.0.0-alpha01
October 28, 2020
android.navigation:navigation-compose:1.0.0-alpha01
is released. Version 1.0.0-alpha01 contains these commits.
New Features
The navigation-compose
artifact provides integration between the Navigation Component and Jetpack Compose. It uses @Composable
functions as the destinations in your application.
This initial release provides:
- A
NavHost
composable that allows you to construct your navigation graph via a Kotlin DSL. - Scoping of lifecycle,
ViewModel
, and remembered state at the destination level. - Automatic integration with the system back button.
- Support for passing arguments, attaching deep links to destinations, and returning a result to previous destinations.
- Compose specific helpers in
rememberNavController()
andcurrentBackStackEntryAsState()
to allow hoisting state and connecting theNavController
to composables outside of theNavHost
(such as a bottom navigation bar).
See the Compose Navigation guide for more information.
Version 2.3.5
Version 2.3.5
April 7, 2021
androidx.navigation:navigation-*:2.3.5
is released. Version 2.3.5 contains these commits.
New Features
- When navigating using a
NavDeepLinkRequest
orUri
, you can now access theUri
, action, and mime type in the resulting destination by getting the intent from arguments viaKEY_DEEP_LINK_INTENT
, mirroring the functionality already available for external deep linking. (I975c3, b/181521877)
Bug Fixes
OnBackPressedCallbacks
added to a dispatcher with theNavBackStackEntry
as the LifecycleOwner now properly intercept back after the Activity Lifecycle isSTOPPED
, thenSTARTED
(Iff94f, b/182284739)- Deep link domain parsing is now case insensitive, ensuring that
www.example.com
matches bothwww.example.com
andwww.Example.com
. Note that query parameter names are still case sensitive. (#144, b/153829033) - Fixed a
NullPointerException
that could occur when a destination has multiple non-nullable default arguments and you navigate to that destination while only overriding a subset of those arguments. (aosp/1644827)
Dependency Updates
- The Navigation Safe Args Gradle Plugin now depends on Kotlin Gradle Plugin 1.4.31. (aosp/1661058, b/181156413)
External Contribution
- Thanks
bentrengrove
for the pull request making deep link domain parsing case insensitive. (#144, b/153829033)
Version 2.3.4
Version 2.3.4
March 10, 2021
androidx.navigation:navigation-*:2.3.4
is released. Version 2.3.4 contains these commits.
New Features
ReferenceType
arguments can now be properly parsed when sent as part of a deeplink URI. This supports both the raw integer value as well as hex values prefixed by0x
. (#127, b/179166693)- The
android:defaultValue
for an argument withapp:argType="float"
now supports integer default values, allowing you to useandroid:defaultValue="0"
rather than requiring the use of0.0
. (#117, b/173766247)
Bug Fixes
- Fix stuck installation progress when using Navigation’s support for dynamic features. (Ib27a7, b/169636207)
- Calling
setViewModelStore
orsetLifecycleOwner
with the same object that has already been set will now be a no-op (Idf491, b/177825470) - Safe-Args now adds suppress annotations on the proper methods when using java. (I8fbc5, b/179463137)
External Contributions
- Thanks
JvmName
for the pull request to ensure thatReferenceType
arguments can now be properly parsed when sent as part of a deeplink URI. (#127, b/179166693) - Thanks
tatocaster
for the pull request to allow thedefaultValue
for an argument withapp:argType=”float”
now supports integer default values. (#117, b/173766247)
Version 2.3.3
Version 2.3.3
January 27, 2021
androidx.navigation:navigation-*:2.3.3
is released. Version 2.3.3 contains these commits.
Bug Fixes
- There is no longer a crash when popping a
NavBackStackEntry
before itsLifecycle
is moved toCREATED
. (Ie3ba3) - Fixed regression caused by b/171364502 where navigating to an
activity with an animation resource value of
0
caused aResourceNotFoundException
. (I7aedb, b/176819931)
Version 2.3.2
Version 2.3.2
December 2, 2020
androidx.navigation:navigation-*:2.3.2
is released. Version 2.3.2 contains these commits.
Bug Fixes
- Fixed a regression in
NavigationUI
where using an<activity>
destination withonNavDestinationSelected
would fail to navigate to the Activity. (I22e34, b/171364502) - Fixed an issue where
navigation-dynamic-features-fragment
would result in navigating to the newly installed destination multiple times. (aosp/1486056, b/169636207) - Fixed an issue where default arguments would not be sent to
OnDestinationChangedListener
instances when usinglaunchSingleTop
. (I2c5cb) - Fixed an issue where navigating to a nested navigation graph would not create a new graph instance on the back stack. (Ifc831)
- Fixed an issue where using
navigate()
with apopUpTo
that removed the last destination in a navigation graph would not immediately destroy and remove the navigation graph itself from the back stack. (I910a3) - Navigation SafeArgs now uses KotlinPoet version 1.7.2 which adds support for Kotlin's explicit API mode. (I918b5)
NavHostFragment.findNavController(Fragment)
now also checks the root decor view of a DialogFragment in addition to the existing checks of the Fragment hierarchy and Fragment's view hierarchy. This allows you to test dialog fragments that use Navigation withFragmentScenario
andNavigation.setViewNavController()
. (I69e0d)
Version 2.3.1
Version 2.3.1
October 14, 2020
androidx.navigation:navigation-*:2.3.1
is released. Version 2.3.1 contains these commits.
New Features
- Default Animator resources have been added to Navigation UI and are recommended over the default animation resources. (b/167430145)
- NavOptions now overrides the hashcode and equals methods (b/161586466)
- Navigation now includes the current destination in the “No destination with ID” IllegalArgumentException, which should improve the developer debugging experience. (b/168311416)
Bug Fixes
- Safe Args will no longer wrap the return line, even if the generated argument class name is longer than 100 characters. (b/168584987)
Dependency Changes
navigation-ui
now depends on DrawerLayout 1.1.1, ensuring thatNavigationUI
is able to open the drawer even when usingLOCK_MODE_LOCKED_CLOSED
orLOCK_MODE_LOCKED_OPEN
. (b/162253907)- Safe Args now depends on KotlinPoet 1.6.0 (aosp/1435911)
- Safe Args now depends on AGP 4.0.1 (aosp/1442337)
Version 2.3.0
Version 2.3.0
June 24, 2020
androidx.navigation:navigation-*:2.3.0
is released. Version 2.3.0 contains these commits.
Major changes since 2.2.0
- Feature Module integration: The
navigation-dynamic-features-runtime
andnavigation-dynamic-features-fragment
artifacts allow you to navigate to destinations that are defined in feature modules, automatically handling the installation of the feature modules as needed. See Navigate with feature modules for more information. - Navigation Testing: The
navigation-testing
artifact provides aTestNavHostController
that allows you to set the current destination and verify the back stack after navigation operations. See Test Navigation for more information. - Returning a Result: The
NavBackStackEntry
associated with each destination on the Navigation back stack now allows you to access aSavedStateHandle
suitable for storing small amounts of saved state that should be associated with a particular back stack entry. See Returning a result to the previous Destination for more information. NavigationUI
support forOpenable
: All usages ofDrawerLayout
inNavigationUI
have been replaced with the more genericOpenable
interface added in CustomView1.1.0
and implemented byDrawerLayout
in DrawerLayout1.1.0
.- Action and Mime Type support in deep links: Deep linking has been expanded to support
app:action
andapp:mimeType
in addition to theapp:uri
previously available.NavController
now supports navigating by any combination of these fields via the newNavDeepLinkRequest
class. See Navigate using NavDeepLinkRequest for more information.
Known Issues
- Support for deep link actions and mime types is not yet available in Manifest Merger. Until that work is completed, any generated
<intent-filter>
elements from the<nav-graph>
element in your manifest won't include your mime type in its<data>
element or your custom<action>
. You must manually add an appropriate<intent-filter>
to your manifest.
Version 2.3.0-rc01
June 10, 2020
androidx.navigation:navigation-*:2.3.0-rc01
is released. Version 2.3.0-rc01 contains these commits.
Bug Fixes
- Fixed a
NullPointerException
when replacing an instance of a destination with no arguments with another instance with arguments withsingleTop
. (b/158006669) - All
destination is unknown
exceptions thrown byNavController
now have additional debugging information to help determine the state of theNavController
. (b/157764916)
Version 2.3.0-beta01
May 20, 2020
androidx.navigation:navigation-*:2.3.0-beta01
are released. Version 2.3.0-beta01 contains these commits.
Bug Fixes
- Fixed an issue where the
Lifecycle
of theNavBackStackEntry
would not be properly updated after process death. (b/155218371) OnDestinationChangedListener
instances registered before callingsetGraph()
are now properly sent the restored destination after a process death. (b/155218371)- When using
singleTop
, theNavBackStackEntry
now correctly has its arguments updated and the updated arguments are sent to allOnDestinationChangeListener
instances. (b/156545508)
Dependency Updates
- The
NavigationUI
artifact now depends on CustomView1.1.0-rc01
and DrawerLayout1.1.0-rc01
. (aosp/1309696)
Version 2.3.0-alpha06
April 29, 2020
androidx.navigation:navigation-*:2.3.0-alpha06
is released. (Version 2.3.0-alpha06 contains these commits.)
New Features
- Deep linking has been expanded to support
app:action
andapp:mimeType
in addition to theapp:uri
previously available. NavController now supports navigating by any combination of these fields via the newNavDeepLinkRequest
class. (b/136573074, b/135334841)
API Changes
- Greatly expanded the Kotlin DSL support for Dynamic Navigation destinations. (b/148969800)
Bug Fixes
- Fixed an issue where deep link Intents would be ignored when using a nested start destination. (b/154532067)
Version 2.3.0-alpha05
April 15, 2020
androidx.navigation:navigation-*:2.3.0-alpha05
is released. Version 2.3.0-alpha05 contains these commits.
New Features
- For dynamic graph includes using
<include-dynamic>
, you no longer need to specifyapp:graphPackage
and a default one will be used by addingmoduleName
suffix to theapplicationId
after a dot. If you do need to customize yourgraphPackage
, an${applicationId}
placeholder is now supported. (b/152696768) - The Navigation Graph Kotlin DSL now exposes a
defaultArguments
Map
for actions, mirroring the ability to set default values on<action>
elements in Navigation XML files. (b/150345605)
Bug Fixes
- From Navigation 2.2.2: Fixed an
IllegalStateException
when deep linking to the start destination of your graph when you have multipleNavHostFragment
instances in your Activity. (b/147378752)
Dependency updates
- Navigation now depends on Fragment
1.2.4
. (aosp/1277325) - Dynamic Navigation now depends on Play Core
1.7.2
. (aosp/1282257)
Version 2.3.0-alpha04
March 18, 2020
androidx.navigation:navigation-*:2.3.0-alpha04
is released. Version 2.3.0-alpha04 contains these commits.
New Features
- Added support for feature module activity and fragment destinations in the Navigation Kotlin DSL. (b/148969800)
API Changes
- The
DynamicExtras
class no longer uses a builder pattern and can now be constructed directly. (aosp/1253671) DynamicActivityNavigator
now takes aContext
in its constructor rather than anActivity
. (aosp/1250252)
Bug Fixes
NavigationUI
no longer ignores empty labels (i.e., a destination withandroid:label=””
) and now correctly sets the title to an empty string. (b/148679860)
Dependency Updates
- The Navigation Dynamic Features artifacts now depend on Play Core
1.6.5
. (b/149556401)
Version 2.3.0-alpha03
March 4, 2020
androidx.navigation:navigation-*:2.3.0-alpha03
is released. Version 2.3.0-alpha03 contains these commits.
API Changes
- Instead of relying on the concrete
DrawerLayout
class,AppBarConfiguration
now uses theOpenable
interface introduced in CustomView1.1.0-alpha02
(whichDrawerLayout
implements as of DrawerLayout1.1.0-alpha04
), allowing you to use custom implementations ofOpenable
withNavigationUI
. (b/129030452)
Bug Fixes
- The
navigation-common-ktx
ProGuard rules now correctly only keep theNavArgs
classes that are used rather than allNavArgs
instances. (b/150213558)
Dependency changes
- Navigation has reverted its dependency on Core
1.2.0
and now depends on Core1.1.0
to avoid forcing developers to move to a newer dependency when Navigation does not depend on any new APIs in Core1.2.0
.
Version 2.3.0-alpha02
February 19, 2020
androidx.navigation:navigation-*:2.3.0-alpha02
is released. Version 2.3.0-alpha02 contains these commits.
New Features
- The
NavBackStackEntry
now allows you to access aSavedStateHandle
suitable for storing small amounts of saved state that should be associated with a particular back stack entry. See Returning a result for an example use case. (b/79672220)
API Changes
- Convenience methods of
getCurrentBackStackEntry()
andgetPreviousBackStackEntry()
have been added to make it easier to retrieve aNavBackStackEntry
for the current and previous destinations. (b/79672220)
Bug Fixes
navigateUp()
now passes the current destination’s arguments and theKEY_DEEP_LINK_INTENT
to the previous destination when launching your app on your own task stack. (b/147456890)
Dependency changes
- Navigation now depends on Core
1.2.0
.
Version 2.3.0-alpha01
February 5, 2020
androidx.navigation:navigation-*:2.3.0-alpha01
is released. Version 2.3.0-alpha01 contains these commits.
New features
- The new
navigation-testing
artifact provides aTestNavHostController
class. This class provides an alternative to using a mockNavController
when testing Navigation that allows you to set the current destination and verify the back stack after navigation operations. (b/140884273) - The new
navigation-dynamic-features-fragment
(and its transitive dependency,navigation-dynamic-features-runtime
) allows you to include destinations or entire navigation graphs (via<include-dynamic>
) from feature modules, providing seamless installation of on-demand feature modules when navigating to those destinations. See Navigate with feature modules for more information. (b/132170186)
Bug fixes
- From Navigation
2.2.1
: Deep links without query parameters now correctly ignore any query parameters rather than appending them to trailing{argument}
elements or not matching the deep link. (b/147447512) - From Navigation
2.2.1
: Thenavigation-ui
ProGuard rules forDrawerArrowDrawable
have been updated to ensure thatandroid.enableJetifier=true
is not required. (b/147610424) - From Navigation
2.2.1
: Thenavigation-common-ktx
module now has a unique manifest package name instead of sharing the same manifest package name asnavigation-runtime-ktx
. (aosp/1141947)
Dependency updates
- From Navigation
2.2.1
: Navigation2.2.1
now depends on Lifecycle ViewModel SavedState2.2.0
and Fragment1.2.1
.
Version 2.2.2
Version 2.2.2
April 15, 2020
androidx.navigation:navigation-*:2.2.2
are released. Version 2.2.2 contains these commits.
Bug Fixes
- Fixed an
IllegalStateException
when deep linking to the start destination of your graph when you have multipleNavHostFragment
instances in your Activity. (b/147378752) NavigationUI
no longer ignores empty labels (i.e., a destination withandroid:label=””
) and now correctly sets the title to an empty string. This was previously released in Navigation 2.3.0-alpha04. (b/148679860)- The
navigation-common-ktx
ProGuard rules now correctly only keep theNavArgs
classes that are used rather than allNavArgs
instances. This was previously released in Navigation 2.3.0-alpha03. (b/150213558
Dependency updates
- Navigation now depends on Fragment
1.2.4
. (aosp/1277325)
Version 2.2.1
Version 2.2.1
February 5, 2020
androidx.navigation:navigation-*:2.2.1
is released. Version 2.2.1 contains these commits.
Bug fixes
- Deep links without query parameters now correctly ignore any query parameters rather than appending them to trailing
{argument}
elements or not matching the deep link. (b/147447512) - The
navigation-ui
ProGuard rules forDrawerArrowDrawable
have been updated to ensure thatandroid.enableJetifier=true
is not required. (b/147610424) - The
navigation-common-ktx
module now has a unique manifest package name instead of sharing the same manifest package name asnavigation-runtime-ktx
. (aosp/1141947)
Dependency updates
- Navigation
2.2.1
now depends on Lifecycle ViewModel SavedState2.2.0
and Fragment1.2.1
.
Version 2.2.0
Version 2.2.0
January 22, 2020
androidx.navigation:navigation-*:2.2.0
is released. Version 2.2.0 contains these commits.
Important changes since 2.1.0
- NavBackStackEntry: You can now call
NavController.getBackStackEntry()
, passing in the ID of a destination or navigation graph on the back stack. The returnedNavBackStackEntry
provides a Navigation-drivenLifecycleOwner
,ViewModelStoreOwner
(the same returned byNavController.getViewModelStoreOwner()
), andSavedStateRegistryOwner
, in addition to providing the arguments used to start that destination. - Lifecycle ViewModel SavedState Integration:
SavedStateViewModelFactory
is now the default factory used when usingby navGraphViewModels()
or theViewModelProvider
constructor with aViewModelStoreOwner
returned byNavController.getBackStackEntry()
orNavController.getViewModelStoreOwner()
. - Query Parameter Support for Deep Links: Deep links with query parameters now support reordered query parameters; arguments that have a default value or are nullable are now optional when matching deep links.
- Improved Animation Support:
NavHostFragment
now usesFragmentContainerView
from Fragment 1.2.0, fixing animation z-ordering issues and window insets dispatching to Fragments.
Version 2.2.0-rc04
December 18, 2019
androidx.navigation:navigation-*:2.2.0-rc04
is released. Version 2.2.0-rc04 contains these commits.
Bug fixes
- Adjusted the default fade animations used by
navigation-ui
to match the adjusted fade animations in Fragment1.2.0-rc04
. (b/145769814)
Version 2.2.0-rc03
December 4, 2019
androidx.navigation:navigation-*:2.2.0-rc03
is released. Version 2.2.0-rc03 contains these commits.
Bug fixes
- Fixed an issue with deep link parsing when using query parameters and an argument as the last part of the path that prevented more than one character of the final path argument from being parsed. (b/144554689)
- Fixed an issue with deep link parsing where optional parameters would receive
"@null"
instead ofnull
. (b/141613546) NavHostFragment
now correctly restores the graph after a configuration change when used withFragmentContainerView
. (b/143752103)
Dependency changes
- Navigation now depends on Lifecycle
2.2.0-rc03
, Lifecycle ViewModel SavedState1.0.0-rc03
, Activity1.1.0-rc03
, and Fragment1.2.0-rc03
where appropriate.
Version 2.2.0-rc02
November 7, 2019
androidx.navigation:navigation-*:2.2.0-rc02
is released. Version 2.2.0-rc02 contains these commits.
Dependency changes
- Navigation now depends on androidx.lifecycle
2.2.0-rc02
.
Version 2.2.0-rc01
October 23, 2019
androidx.navigation:navigation-*:2.2.0-rc01
is released with no changes since 2.2.0-beta01
. Version 2.2.0-rc01 contains these commits.
Version 2.2.0-beta01
October 9, 2019
androidx.navigation:navigation-*:2.2.0-beta01
is released. Version 2.2.0-beta01 contains these commits.
New features
NavDestination
and its subclasses now overridetoString()
to provide more helpful information when debugging. (b/141264986)
Behavior changes
- Extra query parameters are now ignored when matching deep links rather than causing the match to fail. (b/141482822)
Bug fixes
- Fixed an issue where arguments in a deep link’s path would be ignored if query parameters were also specified. (b/141505755)
- The
navArgs()
Kotlin extension onActivity
now has a better error message when there are no extras. (b/141408999) - Safe Args generated
Directions
Java classes now contain default values. (b/141099045) - Safe Args generated
Args
Java classes now contain default values. (b/140123727) - When using a
Toolbar
,NavigationUI
no longer animates the text change when moving between two top level destinations. (b/140848160)
Version 2.2.0-alpha03
September 18, 2019
androidx.navigation:navigation-*:2.2.0-alpha03
is released. Version 2.2.0-alpha03 contains these commits.
Behavior changes
- Calling
setViewModelStore()
after callingsetGraph
now results in anIllegalStateException
. This should always be set by theNavHost
as part of the initial setup to ensure that allNavBackStackEntry
instances have a consistent storage forViewModel
instances. (aosp/1111821)
Bug fixes
- Fixed a
ConcurrentModificationException
when usingViewModel
instances attached to multiple different navigation graph scopedViewModelStore
instances. (aosp/1112257)
Version 2.2.0-alpha02
September 5, 2019
androidx.navigation:navigation-*:2.2.0-alpha02
is released. The commits included in this version can be found here.
New features
- Deep links with query parameters now support reordered query parameters; arguments that have a default value or are nullable are now optional when matching deep links. (b/133273839)
- You can now call
NavController.getBackStackEntry()
, passing in the ID of a destination or navigation graph on the back stack. The returnedNavBackStackEntry
provides a Navigation-drivenLifecycleOwner
,ViewModelStoreOwner
(the same returned byNavController.getViewModelStoreOwner()
), andSavedStateRegistryOwner
, in addition to providing the arguments used to start that destination. (aosp/1101691, aosp/1101710)
Bug fixes
- Fixed an issue where adding a
NavHostFragment
toViewPager2
failed with anIllegalArgumentException
. (b/133640271) NavInflater
now avoids callinggetResourceName()
unnecessarily, speeding up inflation time by up to 40%. (b/139213740)
Version 2.2.0-alpha01
August 7, 2019
androidx.navigation:navigation-*:2.2.0-alpha01
is released. The commits included in this version can be found here.
New features
SavedStateViewModelFactory
is now the default factory used when usingby navGraphViewModels()
or theViewModelProvider
constructor with aViewModelStoreOwner
returned byNavController.getViewModelStoreOwner()
. (b/135716331)
API changes
- From Navigation
2.1.0-rc01
: The deprecatedgetViewModelStore()
API onNavController
introduced in2.1.0-alpha02
has been removed. (aosp/1091021)
Bug fixes
NavHostFragment
now usesFragmentContainerView
, fixing animation z-ordering issues and window insets dispatching to Fragments. (b/137310379)
Version 2.1.0
Version 2.1.0
September 5, 2019
androidx.navigation:navigation-*:2.1.0
is released. The commits included in this version can be found here.
Important changes since 2.0.0
- Scoping ViewModels to a navigation graph: You can now create ViewModels that are scoped at the navigation graph level using the
by navGraphViewModels()
property delegate for Kotlin users using the-ktx
libraries or by using thegetViewModelStoreOwner()
API added toNavController
. See Share UI-related data between destinations for more information. - Dialog destinations: You can now create
<dialog>
destinations that will show aDialogFragment
when younavigate
to them.NavHostFragment
supports dialog destinations by default. See Create a destination from a DialogFragment for more information. - Navigating by Uri: You can now
navigate
using aUri
, which uses the<deepLink>
you’ve added to a destination to navigate there. See Navigate using Uri for more information. - NavHostController: APIs used specifically for constructing a custom
NavHost
have been moved toNavHostController
, allowing implementations to connect theirNavController
to the hostingLifecycleOwner
,OnBackPressedDispatcher
, andViewModelStore
.
Version 2.1.0-rc01
August 7, 2019
androidx.navigation:navigation-*:2.1.0-rc01
is released. The commits included in this version can be found here.
API changes
- The deprecated
getViewModelStore()
API onNavController
introduced in2.1.0-alpha02
has been removed. (aosp/1091021)
Version 2.1.0-beta02
July 19, 2019
androidx.navigation:*:2.1.0-beta02
is released. The commits included in this version can be found here.
Bug fixes
- Removed unintentional jacoco dependency that was introduced in
2.1.0-beta01
. (b/137782950)
Version 2.1.0-beta01
July 17, 2019
androidx.navigation:*:2.1.0-beta01
is released. The commits included in this version can be found here.
New features
NavigationUI
now animates the removal of the Up button when usingsetupWithNavController()
with aToolbar
orCollapsingToolbarLayout
. (b/131403621)
Bug fixes
- Fixed a timing issue when using multiple NavHostFragments with the same container with
findNavController()
. (b/136021571)
Version 2.1.0-alpha06
July 2, 2019
androidx.navigation:*:2.1.0-alpha06
is released. The commits included in this version can be found here.
New features
- The
app:navGraph
attribute used by NavHostFragment has now been moved to thenavigation-runtime
artifact. Custom navigators that can be added via XML should use this attribute to gain integration with the Navigation Editor’s Host panel. (b/133880955)
API changes
- The
getViewModelStore()
API onNavController
has been deprecated in favor of the newgetViewModelStoreOwner()
method that returns aViewModelStoreOwner
. (aosp/987010) - The implementation of floating window destinations, such as
<dialog>
destinations, has been generalized into a marker interface,FloatingWindow
, that all<dialog>
destinations now implement. NavigationUI methods for interacting with the top app bar now ignoreFloatingWindow
destinations. (b/133600763)
Behavior changes
- Navigation now correctly keeps its state in sync with what is seen on the screen when using a
<dialog>
destination. As a consequence, Navigation now automatically pops<dialog>
destinations when you navigate to a non-dialog and non-activity destination, such as a<fragment>
destination. (b/134089818)
Bug fixes
- Navigation now suppresses the animation that occurs when recreating the activity when handling a deep link, fixing a visual flash. (b/130362979)
- Fixed a bug where the Navigation back stack would be out of sync when popping a Fragment as the initial fragment is being added. (b/133832218)
Version 2.1.0-alpha05
June 5, 2019
androidx.navigation:*:2.1.0-alpha05
is released. The commits included in this version can be found here.
API changes
- Host related APIs on
NavController
have been renamed and moved to a new subclass ofNavController
,NavHostController
. (aosp/966091) - The
NavController
setHostOnBackPressedDispatcherOwner()
method has been replaced withNavHostController
’ssetOnBackPressedDispatcher()
method and now requires that you callsetLifecycleOwner()
prior to calling it. (aosp/965409) NavHostController
now contains aenableOnBackPressed(boolean)
method that replaces theNavHostOnBackPressedManager
class that was previously returned bysetHostOnBackPressedDispatcherOwner()
. (aosp/966091)
Bug fixes
- Fixed an issue where the back stack was not correct after navigating by URI. (b/132509387)
- Deep links automatically handled by NavController now only trigger once. (b/132754763)
Version 2.1.0-alpha04
May 16, 2019
androidx.navigation:*:2.1.0-alpha04
is released. The commits included in this version can be found here.
Bug fixes
NavHostFragment
correctly respectsapp:defaultNavHost
when intercepting the system Back button events, fixing a regression in Navigation2.1.0-alpha03
. b/132077777DialogFragmentNavigator
now correctly handlespopBackStack()
andnavigateUp()
operations. b/132576764- Fixed an
IllegalStateException: unknown destination during restore
issue when repeatedly navigating between nested graphs. b/131733658
Version 2.1.0-alpha03
May 7, 2019
androidx.navigation:*:2.1.0-alpha03
is released. The commits included in this version can be found here.
Known Issues
- NavHostFragment continues to intercept the system Back button despite using
app:defaultNavHost="false"
b/132077777
New features
- You can now create
<dialog>
destinations that will show aDialogFragment
when younavigate
to them.NavHostFragment
supports dialog destinations by default. b/80267254 - In addition to calling
navigate
with a resource id or aNavDirections
instance, you can now navigate via aUri
, which uses the<deepLink>
you’ve added to a destination to navigate to the correct destination. b/110412864
Behavior changes
- The default animations provided by NavigationUI have been sped up from 400ms to 220ms to match the default animation speed of activities and fragments. b/130055522
API changes
- The
createFragmentNavigator()
method ofNavHostFragment
has been deprecated and its functionality moved to the newonCreateNavController()
method to make it more clear that this is the correct entry point of adding custom Navigators when subclassingNavHostFragment
. b/122802849 - A
hasDeepLink()
method has been added toNavDestination
to allow you to check if a givenUri
can be handled by that destination or, in the case of aNavGraph
, any destination in the navigation graph. b/117437718
Bug fixes
- Default arguments are now correctly passed to
OnDestinationChangedListener
instances. b/130630686 NavHostFragment
now intercepts system Back events using theOnBackPressedDispatcher
, fixing an issue when doing conditional navigation in Fragment lifecycle methods upon returning to a Fragment. b/111598096- For Safe Args, an
android:defaultValue=”@null”
with an unspecifiedapp:argType
is now properly inferred as astring
argument. b/129629192
Version 2.1.0-alpha02
April 3, 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 thegetViewModelStore()
API added toNavController
. b/111614463
API changes
- You can now add an
app:targetPackage
to an<activity>
destination to limit the matching package name. It supportsapp: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
andandroidx.fragment:fragment:1.1.0-alpha05
. This release also removes the dependency onandroidx.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 usesFragmentFactory
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 usingandroid: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
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
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 withoutFLAG_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
andfun
in the package name associated with theR
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 anandroid:defaultValue
forreference
arguments. b/124248602
Behavior changes
- Exact deep link matches are now prioritized over deep links with
.*
or argument matches. b/123969518
Bug Fixes
popBackStack()
andnavigateUp
now correctly returnfalse
when popping the last destination on the back stack, fixing a regression introduced in1.0.0-beta01
. b/123933201- Navigation now correctly sets the
ClassLoader
during restoration of saved instance state, avoiding issues when using custom classes inNavigator
saved state or in arguments sent to aNavDestination
. 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 differentapp: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 theNavController
's state, causing anIllegalStateException
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 generatedNavArgs
class in anActivity
orFragment
. 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 previousandroidx.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 aNavController
will now reset the back stack. b/111450672 - Unknown deep links no longer throw an
IllegalStateException
, but are ignored, fixing issues with nested or multipleNavHostFragment
s. b/121340440
Breaking Changes
- The
NavOptions.applyPopAnimationsToPendingTransition()
method for applying pop animations to an Activity has been moved toActivityNavigator
. 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
fromNavDirections
'getArguments()
is now marked as@NonNull
rather than@Nullable
. b/123243957
Bug Fixes
NavDeepLinkBuilder
now correctly handles multiple simultaneousPendingIntent
s to the same destination by using the arguments you pass in to determine the uniqueness. b/120042732NavController
now correctly handlespopBackStack()
operations when using a nestedNavHostFragment
or other child Fragments with a back stack. b/122770335NavigationUI
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 equalhashCode()
values whenequals()
would return true. b/123043662 FragmentNavigator
now throws a better error message if you attempt to do customFragmentTransactions
on theNavHostFragment
'sFragmentManager
. You should always usegetChildFragmentManager()
. 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
MenuItem
s withmenuCategory="secondary"
will no longer pop the back stack when used withNavigationUI
methods. b/120104424AppBarConfiguration
now allows you to set a fallbackOnNavigateUpListener
instance which will be called whennavController.navigateUp()
returnsfalse
. b/79993862 b/120690961
Breaking Changes
- When using an
<argument>
with anargType="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 thesetup
methods. AddmenuCategory="secondary"
to yourMenuItem
to avoid popping the back stack. aosp/852869- The
fromBundle()
methods of generatedArgs
classes now take a non-nullBundle
instead of a nullableBundle
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, 2018
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 yourandroid:label
with the correct argument b/80267266 - Navigation now depends on Support Library 28.0.0 b/120293333
Breaking Changes
OnNavigatedListener
has been renamed toOnDestinationChangedListener
b/118670572OnDestinationChangedListener
now also passes theBundle
of arguments aosp/837142- The
app:clearTask
andapp:launchDocument
attributes and their associated methods have been removed. Useapp:popUpTo
with the root of your graph to remove all destinations from your back stack. b/119628354 ActivityNavigator.Extras
now uses aBuilder
pattern and adds the ability to set anyIntent.FLAG_ACTIVITY_
flags aosp/828140NavController.onHandleDeepLink
has been renamed tohandleDeepLink
aosp/836063- Many classes and methods not meant for subclassing, such as
NavOptions
,NavInflater
,NavDeepLinkBuilder
, andAppBarConfiguration
, have been madefinal
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 aFragmentFactory
. b/119054429 - The constructor for
NavGraphNavigator
no longer takes aContext
aosp/835340 - NavigatorProvider is now
a class, rather than an interface. The
NavigatorProvider
returned bygetNavigatorProvider()
has not changed its functionality. aosp/830660 NavDestination.navigate()
has been removed. Callnavigate()
on theNavigator
instead. aosp/830663- Significant refactoring of
Navigator
, removing the need forOnNavigatorNavigatedListener
and instead havingnavigate
return theNavDestination
that was navigated to. Navigator
instances can no longer send pop events to theNavController
. Consider using aOnBackPressedCallback
to intercept back button presses and callnavController.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 callingtoString()
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 thenavigation-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 aNavigator.Extras
parameter. - NavController's
getGraph()
method is nowNonNull
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 toapp: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 becomesetDemoControllerIndex
b/79995048 - E.g.
action_show_settings
will becomeactionShowSettings
b/79642240
- E.g.
- 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()
andhashCode()
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 usessetReorderingAllowed(true)
. b/109826220Navigation now URLDecodes arguments parsed from deep links URLs. b/79982454
Bug Fixes
Fixed an
IllegalStateException
when calling navigate from Fragment lifecycle methods. b/79632233Navigation 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/79656847Fixed a
StackOverflowError
when using NavDeepLinkBuilder. b/109653065Fixed an
IllegalArgumentException
when navigating back to a nested graph. b/80453447Fixed an issue with overlapping Fragments when using
launchSingleTop
. b/79407969Navigation 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 inNavOptions
has been deprecated. b/80338878The
launchDocument
attribute for actions and the associated API inNavOptions
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
.