navigationevent
Latest Update | Stable Release | Release Candidate | Beta Release | Alpha Release |
---|---|---|---|---|
July 30, 2025 | - | - | - | 1.0.0-alpha05 |
Declaring dependencies
To add a dependency on navigationevent, 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 { implementation "androidx.navigationevent:navigationevent:1.0.0-alpha05" }
Kotlin
dependencies { implementation("androidx.navigationevent:navigationevent:1.0.0-alpha05") }
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.
There are no release notes for this artifact.
Version 1.0
Version 1.0.0-alpha05
July 30, 2025
androidx.navigationevent:navigationevent-*:1.0.0-alpha05
is released. Version 1.0.0-alpha05 contains these commits.
Parent-Child Hierarchy Support:
A NavigationEventDispatcher
can now have parent and child dispatchers, forming a hierarchical tree structure. This enables navigation events to propagate and be managed more flexibly across complex Compose UI components by reflecting the UI’s structural hierarchy through chained dispatchers. (I194ac)
// Create a parent dispatcher that will manage navigation events at a higher level.
val parentDispatcher = NavigationEventDispatcher()
// Create a child dispatcher linked to the parent, forming a hierarchy.
val childDispatcher = NavigationEventDispatcher(parentDispatcher)
The hierarchical isEnabled
property allows for top-down control of a dispatcher. When isEnabled
is set to false
on a dispatcher, it automatically disables all its descendant dispatchers. This feature enables entire branches of the navigation event system to be toggled off efficiently. (I9e985)
// Disabling the child dispatcher disables all its callbacks and any of its children recursively.
childDispatcher.isEnabled = false
Moreover, the isEnabled
property on NavigationEventCallback
now respects the enabled state of its associated dispatcher. This means a callback is considered enabled only if both the callback itself and its dispatcher (including its ancestors) are enabled, ensuring consistent hierarchical control over callback activation. (I1799a)
// Create a test callback and add it to the child dispatcher.
val callback1 = TestNavigationEventCallback(isEnabled = true)
childDispatcher.addCallback(callback1)
// Since the childDispatcher is disabled, the callback is effectively disabled as well.
assertThat(callback1.isEnabled).isFalse()
A new dispose()
method has been introduced for proper cleanup of dispatchers and their children. Calling dispose()
stops listeners to prevent memory leaks, recursively disposes all child dispatchers, removes all callbacks registered to the dispatcher, and unlinks it from its parent. This guarantees resources are released correctly when dispatchers are no longer needed. (I9e985)
// Dispose the child dispatcher to clean up resources.
childDispatcher.dispose()
If any public method is called on a disposed dispatcher, an IllegalStateException
is thrown immediately. This prevents silent failures and helps developers identify improper usage during development. (Ic2dc3)
val callback2 = TestNavigationEventCallback()
// Attempting to use a disposed dispatcher will throw an exception.
assertThrows<IllegalStateException> {
childDispatcher.addCallback(callback2)
}
Note: We will introduce a new NavigationEventDispatcherOwner
Composable that automatically manages a child dispatcher within Compose UI in aosp/3692572. However, this change did not make it into the current release cut and is planned for the next one.
Navigation Testing Library
- Add
navigationevent-testing
module to provide dedicated testing utilities for thenavigationevent
library. (0e50b6) - Add
TestNavigationEventCallback
fake utility class for testing. It records callback method calls and stores receivedNavigationEvent
items to support verification. (4a0246) - Add
TestNavigationEvent
fake utility function to createNavigationEvent
instances with default values, simplifying unit tests for navigation event processing. (3b63f5) - Add
TestNavigationEventDispatcherOwner
fake utility class for testing. It tracks fallback and enabled-state-changed event counts to support interaction verification in tests. (c8753e)
API Changes
- Move
NavigationEventInputHandler
fromandroidMain
tocommonMain
to make it available in KMP common code. Add newpublic send*
methods for dispatching events. Change dispatch functions onNavigationEventDispatcher
frompublic
tointernal
; users must now useNavigationEventInputHandler
to send events. (Ia7114) - Rename
NavigationInputHandler
toOnBackInvokedInputHandler
. (I63405)
Bug Fixes
- Refactor
NavigationEventDispatcher
to reduce overhead by avoiding intermediate list allocations and improving callback dispatch performance. (I82702, I1a9d9) - Add
@FloatRange
annotations totouchX
,touchY
, andprogress
fields inNavigationEvent
to enforce valid value ranges at compile time and improve API safety. (Iac0ec)
Version 1.0.0-alpha04
July 2, 2025
androidx.navigationevent:navigationevent-*:1.0.0-alpha04
is released. Version 1.0.0-alpha04 contains these commits.
Bug Fixes
- Used
implementedInJetBrainsFork
tonavigationevent-compose
and added acommonStubs
target to match Compose conventions. Change requested by JetBrains. (f60c79) - Fixed application of the Compose compiler plugin for Kotlin/Native to ensure correct stub generation. No impact on public APIs or behavior. (1890c9)
Version 1.0.0-alpha03
June 18, 2025
androidx.navigationevent:navigationevent-*:1.0.0-alpha03
is released. Version 1.0.0-alpha03 contains these commits.
New Features
- Introduced a new
navigationevent-compose
module to support Jetpack Compose features in thenavigationevent
library. (980d78) NavigationEvent
Compose has added a newLocalNavigationEventDispatcherOwner
local composition. It returns a nullable value to better determine whether it is available in the current composition.NavigationEventHandler
will now throw an error if the underlying owner is not found. (62ffda)NavigationEvent
Compose has added a newNavigationEventHandler
Composable to handle (predictive back gesture) events. It provides aFlow
ofNavigationEvent
objects that must be collected in the suspending lambda you provide c42ba6 :
NavigationEventHandler { progress: Flow<NavigationEvent> ->
// This block is executed when the back gesture begins.
try {
progress.collect { backEvent ->
// Handle gesture progress updates here.
}
// This block is executed if the gesture completes successfully.
} catch (e: CancellationException) {
// This block is executed if the gesture is cancelled
throw e
} finally {
// This block is executed either the gesture is completed or cancelled
}
}
API Changes
- Each
NavigationEventCallback
can now be registered with only oneNavigationEventDispatcher
at a time; adding it to multiple dispatchers throws anIllegalStateException
. Note that this behavior differs fromOnBackPressedDispatcher
, which allows multiple dispatchers. (e82c19) - Made
isPassThrough
aval
to prevent mutation during navigation, which could breakNavigationEvent
's dispatching. (I0b287)
Version 1.0.0-alpha02
June 4, 2025
androidx.navigationevent:navigationevent-*:1.0.0-alpha02
is released. Version 1.0.0-alpha02 contains these commits.
API Changes
- Replace
NavigationEventDispatcher
's secondary constructor with default arguments. (I716a0) - Remove priority property from
NavigationEventCallback
. Pass priority toNavigationEventDispatcher.addCallback()
instead. (I13cae)
Bug Fixes
- Fixed a
ConcurrentModificationException
that could occur whenNavigationEventCallback.remove()
was called due to simultaneously modifying the internal list of closeables. (b/420919815)
Version 1.0.0-alpha01
May 20, 2025
androidx.navigationevent:navigationevent-*:1.0.0-alpha01
is released. Version 1.0.0-alpha01 contains these commits.
New Features
- The
androidx.navigationevent
library provides a KMP-first API for handling system back as well as Predictive Back. TheNavigationEventDispatcher
serves as a common APIs for registering one or moreNavigationEventCallback
instances for receiving system back events. - This layer sits below the previously released APIs in
androidx.activity
and aims to be a less opinionated replacement for using the Activity APIs in higher level components or directly using the Android frameworkOnBackInvokedDispatcher
APIs. Theandroidx.activity
APIs have been rewritten on top of the Navigation Event APIs as part of Activity 1.12.0-alpha01.