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
August 13, 2025 - - - 1.0.0-alpha06

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

Kotlin

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

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-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.