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

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