navigationevent

  
The Navigation Event library provides a KMP-first API for handling system back as well as Predictive Back.
Latest Update Stable Release Release Candidate Beta Release Alpha Release
October 8, 2025 - - 1.0.0-beta01 -

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-beta01"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.0.0-beta01")
}

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.

Create a new issue

See the Issue Tracker documentation for more information.

There are no release notes for this artifact.

Version 1.0

Version 1.0.0-beta01

October 08, 2025

androidx.navigationevent:navigationevent-*:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

API Changes

  • Correct the FloatRange annotation for NavigationEvent.touchX and NavigationEvent.touchY. These values represent absolute pixel coordinates and do not have a 1.0 upper bound. (I4b205, b/445989313)
  • Refactor the NavigationEventDispatcherOwner composable to rememberNavigationEventDispatcherOwner. The function now returns the NavigationEventDispatcherOwner directly. To provide this owner to a sub-composition, use CompositionLocalProvider. (I874b2, b/444446629)

Version 1.0.0-alpha09

September 24, 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha09 is released. Version 1.0.0-alpha09 contains these commits.

API Changes

  • Use the NavigationEventTransitionState.Idle singleton object directly instead of instantiating Idle(). (Ic7d9e, b/444734264)
  • Make convenience constructors internal; obtain instances via public NavigationEventDispatcher.history instead of direct construction. (I3b7e0, b/444734264)
  • Require creating NavigationEventState via rememberNavigationEventState; constructor is now internal. (Ie143c, b/444734264)
  • Adopt onBackCompletedFallback replace fallbackOnBackPressed usages and constructor parameter. Behavior is unchanged; invoked only on completed, unhandled back events. (Idabe9, b/444734264)
  • The primary constructor of NavigationEventHistory(mergedHistory, currentIndex) is now internal. External consumers must use the public constructors (either the empty constructor or the partition-based constructor) to create instances. (I1c047, b/444734264)
  • Make View.setViewTreeNavigationEventDispatcherOwner accept nullable owner (Ic9eb6, b/444436762)
  • NavigationEventInfo is now an abstract class instead of an interface. Update all custom implementations to inherit from the class (e.g, data class MyInfo : NavigationEventInfo()). (I1e59c, b/444734264)
  • The legacy NavigationEventDispatcher.state property and getState<T>() function have been removed. Use the new, separate dispatcher.transitionState (for gesture progress) and dispatcher.history (for the navigation stack) flows. (Ic2ceb, b/444734264)
  • The NavigationEventInput.onInfoChanged(...) callback is replaced. Implement the new onHistoryChanged(history: NavigationEventHistory) callback to receive updates as a single NavigationEventHistory object. (I23e0b, b/444734264)
  • Introduce a new global NavigationEventDispatcher.history StateFlow. This non-generic flow allows observers to subscribe only to changes to the navigation stack and remains stable during gesture progress. This is the counterpart to transitionState. (I1db10, b/444734264)
  • Introduce a new global NavigationEventDispatcher.transitionState StateFlow. This non-generic flow allows observers to subscribe only to the physical gesture state (Idle/InProgress), separate from history. (I171fa, b/444734264)
  • Introduce the NavigationEventHistoryState class. This will serve as the core API for observing navigation information history, separate from gesture state. (I81ca5, b/444734264)
  • NavigationEvent is now marked as @Immutable, allowing the Compose Compiler to optimize recompositions. (If78c7, b/444734264)
  • The navigationevent-compose handler APIs are updated. NavigationEventHandler and NavigationBackHandler (and variants) now support a new overload that accepts a hoisted NavigationEventStates. The simple overloads (taking currentInfo) are preserved and now use this new state model internally. (Ic3251, b/444734264)
  • Add the new @Stable NavigationEventState<T> state holder to the navigationevent-compose library. This object combines local history with local gesture state and will be the primary link between rememberNavigationEventState and NavigationEventHandler. (Ifb69f, b/444734264)
  • Add a new public, read-only transitionState: TransitionState property to NavigationEventHandler. Handlers now maintain their own transition state, which external systems can observe. (I9acd2, b/444734264)
  • Introduce the new TransitionState sealed class. This will serve as the core API for observing gesture state, separate from navigation history. (Id4beb, b/444734264)
  • Expose currentInfo, backInfo, and forwardInfo as public, read-only properties on NavigationEventHandler. (Ia7636, b/444734264)
  • Implementations of NavigationEventHandler must now provide an initialInfo: T value to the base constructor. (Idcfea, b/444734264)
  • Replace OnBackInvokedInput with OnBackInvokedOverlayInput or OnBackInvokedDefaultInput. (I5323f, b/428948766)
  • Mark NavigationEventState as @Immutable. This improves Compose performance by ensuring Composables observing this state can correctly skip recomposition. (I399c8)
  • Rename NavigationEventInfo.NotProvided to NavigationEventInfo.None; update references. No behavior change. (I5e2d4)
  • NavigationEventInfo is now marked as @Immutable, allowing the Compose Compiler to optimize recompositions. (I7c112)
  • Improve Java ergonomics with fun interface for back completion fallback. (I8a860)
  • Rename onHasEnabledHandlerChanged to onHasEnabledHandlersChanged. This clarifies that the callback reports on the collective enablement state of all handlers, not just one. (I1af61, b/443711297)
  • Remove hasEnabledHandler() from NavigationEventDispatcher; use NavigationEventInput.onHasEnabledHandlersChanged instead. (Idef72, b/443711297)
  • Add onInfoChanged callback to NavigationEventInput to notify listeners of changes to the navigation history. This provides the full context of the current, back, and forward stacks, enabling Inputs to react to the contextual information. (I69a8b, b/443282983)
  • Make NavigationEvent's swipeEdge an @IntDef (Icee54, b/443950342)
  • Add a priority parameter to NavigationEventDispatcher.addInput to scope a dispatcher to one priority; events such as onHasEnabledCallbacksChanged now fire only when callbacks at that priority change. (I3e488, b/443711297)
  • Rename NavigationEventDispatcher param from parentDispatcher to parent for clarity. (Id4f1f, b/443801782)
  • Remove NavigationEventPriority in favor of @IntDef for Java users (I10a9f, b/440514265)
  • Enforce navigation handler contract. If your NavigationEventHandler sets isBackEnabled or isForwardEnabled to true, you must now override onBackCompleted or onForwardCompleted respectively. The default implementations now throw an exception to prevent silent failures. (I17c62)
  • Enforce valid priority values when adding navigation event handlers. Calling addHandler with an unsupported priority will now throw an IllegalArgumentException, providing immediate feedback for incorrect usage across all target platforms. (I3c474)

Bug Fixes

  • Make addHandler idempotent; ignore duplicate registrations. (I052aa, b/444734264)
  • Keep NavigationEventState properties in sync during recomposition. (Ib3b4d, b/444734264)
  • Ensure NavigationEventInputs receive the current contextual info (current, back, forward) immediately upon registration. (Ie65bf, b/443282983)

Version 1.0.0-alpha08

September 10, 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha08 is released. Version 1.0.0-alpha08 contains these commits.

New Features

  • Introduce a lambda-based NavigationEventHandler API that replaces the Flow-based handler. Handle back and forward gestures with simple callbacks instead of collecting flows, reducing boilerplate and avoiding cancellation issues. Provide NavigationBackHandler and NavigationForwardHandler as targeted convenience APIs. Remove the Flow-based NavigationEventHandler; migrate to the new callbacks. (I23bac, b/436248277)
  • Allow passive listeners to access the full navigation back stack through combined back info. Enable UIs to render previews and nested navigation history instead of being limited to the top-most callback. (I7a510, b/436248277)
  • Introduce an explicit back/current/forward model to clarify navigation state and support forward navigation with nested handlers. (Ib86da, b/420443609)
  • Add onForward* methods and isForwardEnabled to NavigationEventCallback. (Ic100f, b/436248290)
  • Add forward navigation support to NavigationEventInput. (I5734b)

API Changes

  • Enable testing of forward navigation events with TestNavigationEventCallback. Use isForwardEnabled and onForward* hooks. (I21fb5, b/420443609)
  • Rename onEvent* callbacks to onBack* in NavEvent. (I228b3, b/436248290)
  • Convert SwipeEdge to an inline class. (Id5e01)
  • Make the navigationevent library interoperable with Java. All public APIs are now fully accessible from Java code, enabling seamless integration into mixed-language or Java-only projects. (Ibc944,I5465f, I9fb1e, b/440532890b/443040294)
  • Clarify API roles by renaming NavigationEventCallback to NavigationEventHandler. This change better reflects the class's purpose of handling multi-stage navigation gestures. The corresponding addCallback method is now addHandler. (I2492a, b/443040331)

Bug Fixes

  • Prevent back fallback from running on forward navigation. (I74814, b/436248290)
  • Add support for predictive forward navigation. NavigationEvent APIs now handle both back and forward gestures, enabling consistent animations for both navigation directions. (Idc98c, b/436248290)
  • Prevent an IllegalStateException crash during recomposition when a child NavigationEventDispatcherOwner is removed. (Iff50c, b/412629020)
  • Passive listeners can now access the full navigation back stack through combined back info, enabling UIs to render previews and nested navigation history instead of being limited to the top-most callback. (I7a510, b/436248277)

Version 1.0.0-alpha07

August 27, 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha07 is released. Version 1.0.0-alpha07 contains these commits.

API Changes

  • Remove NavigationEventDispatcher.onHasEnabledCallbacksChanged. (I50e97)
  • Make NavigationEventCallback.onEventCompleted() abstract. (I36b38)
  • Change NavigationEventCallback#on* methods to protected. Update calling code to override them. (I6b691)
  • Rename DirectNavigationEventInput functions. (Iffb62)
  • Rename NavigationEventInput.onAttach to onAdded. (I2d0b8)
  • Rename NavigationEventInput.onDetach to onRemoved. (I2d0b8)
  • Rename NavigationEventInputHandler to NavigationEventInput. (I676a4)
  • Add @EmptySuper to NavigationEventInput.onHasEnabledCallbacksChanged. (If9853)
  • Implement onAttach in NavigationEventInputHandler. (I03648)
  • Implement onDetach in NavigationEventInputHandler. (I03648)
  • Default NavigationEventCallback to enabled upon creation. (Ic0188)
  • Replace NavigationEventInput.addOnHasEnabledCallbacksChangedCallback with NavigationEventInput.onHasEnabledCallbacksChanged. (I64e93)
  • Require the main thread for NavigationEventDispatcher.addInput. (Ic2930)
  • Require the main thread for NavigationEventDispatcher.removeInput. (Ic2930)
  • Remove Dispatcher.addOnHasEnabledCallbacksChangedCallback. Replace with Dispatcher.onHasEnabledCallbacksChanged. (Ida3e3, b/436530096)

Bug Fixes

  • Fix bug where adding an already-attached handler or removing an unattached one triggered incorrect lifecycle logic. (I9e47b)

Version 1.0.0-alpha06

August 13, 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha06 is released. Version 1.0.0-alpha06 contains these commits.

New Features

Passive Listeners API

You can now pass custom contextual information from any navigation host and passively listen to gesture state changes from anywhere in your UI. This enables context-aware animations for predictive back and other gesture-driven navigation.

This feature has two parts:

  1. Providing Info - Use NavigationEventInfo to carry custom data.
  2. Consuming State - Use dispatcher.state (NavigationEventState) to observe gesture progress and context.
  • NavigationEventCallback now exposes setInfo(currentInfo, previousInfo) method to set gesture context in one call (I1d5e7, b/424470518).
  • NavigationEventHandler adds a new overload that accepts currentInfo and previousInfo, making it the primary API for supplying context in Compose apps (I6ecd3, b/424470518).

Example:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • NavigationEventDispatcher now exposes dispatcher.state and dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). These StateFlow-based APIs let any UI observe gesture progress and contextual data without handling the event directly.

Example:

  val gestureState by LocalNavigationEventDispatcherOwner.current!!
      .navigationEventDispatcher
      .state
      .collectAsState()

  val progress = gestureState.progress // Returns latestEvent.progress or 0F

  when (val state = gestureState) {
      is InProgress -> {
          val toScreen = state.currentInfo as MyScreenInfo
          val fromScreen = state.previousInfo as MyScreenInfo
          println("Navigating from ${fromScreen.screenName} to ${toScreen.screenName}")
      }
      is Idle -> { /* Idle state */ }
  }

  • Add progress property to NavigationEventState (I7b196) that returns latestEvent.progress when in progress, or 0F otherwise:

    val progress = state.progress

  • Add NavigationEventDispatcherOwner composable to create, link, and dispose of NavigationEventDispatcher instances hierarchically. Enable dynamic control of the dispatcher's enabled state and automatic cleanup.

    @Composable
fun Sample() {
    NavigationEventDispatcherOwner(enabled = true) {
        val localDispatcherOwner = LocalNavigationEventDispatcherOwner.current
    }
}

API Changes

  • The isPassthrough parameter has been removed from the NavigationEventCallback. (I99028, b/424470518)
  • NavigationEventState constructors are now internal. For testing, update the state (defaults to Idle) via the DirectNavigationEventInputHandler. Call handleOnStarted or handleOnProgressed to set state to InProgress, and handleOnCompleted or handleOnCancelled to return it to Idle. To update NavigationEventInfo, use NavigationEventCallback.setInfo. (I93dca, b/424470518)
  • Added default parameters to NavigationEvent to allow for easier instantiation and to simplify testing which should be used in place of TestNavigationEvent. (I5dc49, I232f4)
  • Added a TestNavigationEventCallback for testing navigation events with specific current/previous states. (Idd22e, b/424470518)
  • NavigationEventInputHandler has been made into an abstract class to replace the previous AbstractNavigationEventInputHandler with an implementation in DirectNavigationEventInputHandler (Iadde5, Ifed40I3897c, b/432616296, b/435416924)
  • The send* functions in NavigationEventInputHandler have had their prefixes renamed to handle*. (Iffcaf)
  • OnBackInvokedInputHandler now extends the newly abstract NavigationInputHandler. (Ib45aa)
  • Changed NavigationEventDispatcherOwner to require a parent dispatcher where you must explicitly pass null to create a root dispatcher. (Ia6f64, b/431534103)

Bug Fixes

  • Improved efficiency by avoiding collection copies in NavigationEventDispatcher.dispose(). (I4ab09)
  • Fixed an issue where the NavigationEventHandler did not correctly respond to changes in its enabled state. (Ia5268,I19bec, I5be5c, b/431534103)

Docs Updates

  • KDocs for NavigationEvent expanded to clarify its role as a unified event wrapper and detail property behavior across different navigation types (gestures, clicks). (I91e8d)
  • Updated documentation for system back handling Compose APIs (BackHandler, PredictiveBackHandler, NavigationEventHandler) to call out behavior specifically around callback order. (I7ab94, )

Dependency Update

  • NavigationEvent now depends on Compose Runtime 1.9.0-beta03 which allows the navigationevent-compose artifact to support all KMP targets. (Ia1b87)

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 the navigationevent library. (0e50b6)
  • Add TestNavigationEventCallback fake utility class for testing. It records callback method calls and stores received NavigationEvent items to support verification. (4a0246)
  • Add TestNavigationEvent fake utility function to create NavigationEvent 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 from androidMain to commonMain to make it available in KMP common code. Add new public send* methods for dispatching events. Change dispatch functions on NavigationEventDispatcher from public to internal; users must now use NavigationEventInputHandler to send events. (Ia7114)
  • Rename NavigationInputHandler to OnBackInvokedInputHandler. (I63405)

Bug Fixes

  • Refactor NavigationEventDispatcher to reduce overhead by avoiding intermediate list allocations and improving callback dispatch performance. (I82702, I1a9d9)
  • Add @FloatRange annotations to touchX, touchY, and progress fields in NavigationEvent 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 to navigationevent-compose and added a commonStubs 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 the navigationevent library. (980d78)
  • NavigationEvent Compose has added a new LocalNavigationEventDispatcherOwner 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 new NavigationEventHandler Composable to handle (predictive back gesture) events. It provides a Flow of NavigationEvent 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 one NavigationEventDispatcher at a time; adding it to multiple dispatchers throws an IllegalStateException. Note that this behavior differs from OnBackPressedDispatcher, which allows multiple dispatchers. (e82c19)
  • Made isPassThrough a val to prevent mutation during navigation, which could break NavigationEvent'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 to NavigationEventDispatcher.addCallback() instead. (I13cae)

Bug Fixes

  • Fixed a ConcurrentModificationException that could occur when NavigationEventCallback.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. The NavigationEventDispatcher serves as a common APIs for registering one or more NavigationEventCallback 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 framework OnBackInvokedDispatcher APIs. The androidx.activity APIs have been rewritten on top of the Navigation Event APIs as part of Activity 1.12.0-alpha01.