Navigation Event

Common guidelines

• For architecture concepts : To understand the foundational architecture, continuous gesture event lifecycles, or class definitions of the Navigation Event library, read Navigation Event overview.
• For Android target : If compile SDK is lower than 36, set it to 36 or higher in build.gradle.kts.
• For Compose Android target: The project must use Jetpack Compose for Compose-specific APIs. This skill is scoped exclusively to Compose Android (Android Views and non-Compose implementations are excluded).
• For activity dispatchers : ComponentActivity automatically implements NavigationEventDispatcherOwner out-of-the-box. You must use the built-in navigationEventDispatcher without creating anonymous delegate owners or overriding member properties.
• For dialog scoping : Floating windows (Compose Dialog, ModalBottomSheet, ComponentDialog) automatically provide a NavigationEventDispatcherOwner. You don't need manual CompositionLocalProvider propagation for dialogs.
• For parent-child dispatcher hierarchies : When scoping navigation handling to ViewPagers, tabbed interfaces, or nested navigation containers in Compose, use rememberNavigationEventDispatcherOwner() to create a child owner linked to the parent. Disabling the owner (enabled = false) automatically cascades to disable all child handlers.
• For Compose handlers : A one-to-one relationship between NavigationEventState and handlers is strictly enforced. Never bind the same NavigationEventState to multiple active NavigationBackHandler instances (IllegalArgumentException).

Step 1: Plan

To complete this step, you MUST ensure the following:

1. Identify the target platform : Verify the app is targeting Compose Android. If compileSdk is lower than 36, set it to 36 or higher in build.gradle.kts.
2. Navigation check: Check if Navigation 3 is in use. If it is in use, use Navigation 3's built-in back navigation support rather than manually implementing low-level dispatchers from this skill.
3. Hierarchy check : Identify host Activities, ViewPagers, tabbed interfaces, or nested navigation hosts that require back gesture interception or parent-child dispatcher linking.
4. Migration check : Check if the project is migrating from back handling (OnBackPressedCallback, BackHandler, onBackPresser) to NavigationEvent and NavigationBackHandler.
5. Input interception : Detect where the app is intercepting navigation events from gestures or hardware button presses requiring translation to NavigationEvent.

Step 2: Set up dependencies

To complete this step, you MUST ensure the following:

• For setting up compile SDKs, declaring catalog versions, and adding dependencies, follow setup guide.

Step 3: Configure dispatcher and inputs

To complete this step, you MUST ensure the following:

• To configure your dispatcher, leverage automatic ComponentActivity or ComponentDialog owner resolution.
• Link parent-child dispatchers in Compose following dispatcher guide.

Step 4: Handle back navigation and UI transitions

To complete this step, you MUST ensure the following:

• To create navigation event handlers, integrate back gesture interception in Compose, animate UI components during swipes, and migrate from legacy back handlers, follow handle back guide.

Step 5: Clean up resources

[!WARNING] Warning: Compose APIs perform teardown automatically. When using Compose APIs such as NavigationBackHandler and rememberNavigationEventDispatcherOwner(), handler removal and dispatcher disposal occur automatically when the composable leaves the composition.

You MUST perform explicit manual cleanup only when managing custom dispatchers or non-Compose handlers:

• Call remove() on active handlers during teardown.
• Call isEnabled = false to temporarily disable navigation subtrees.
• Call dispose() on dispatcher instances when hosting components are destroyed. Disposing a parent dispatcher automatically cascades to all child dispatchers.

Core troubleshooting guidelines

1. Activity dispatcher setup (StackOverflowError recursion)

ComponentActivity implements NavigationEventDispatcherOwner automatically out-of-the-box. Don't override navigationEventDispatcher or wrap it in an anonymous delegate owner.

RIGHT

Why this is RIGHT : Compose apps use ComponentActivity as the host. LocalNavigationEventDispatcherOwner.current automatically resolves the Activity's built-in dispatcher.

// RIGHT
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MyApplicationContent()
        }
    }
}

<br />

WRONG

Why this is WRONG : Implementing NavigationEventDispatcherOwner directly on MainActivity and overriding navigationEventDispatcher with a new instance shadows the library's extension property, causing a recursive infinite loop crash on launch (StackOverflowError). Creating redundant anonymous delegate owners (object : NavigationEventDispatcherOwner) is unnecessary.

// WRONG
class MainActivity : ComponentActivity(), NavigationEventDispatcherOwner {
    override val navigationEventDispatcher = NavigationEventDispatcher() // Shadow loop crash
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MyApplicationContent()
        }
    }
}

<br />

2. Floating window and dialog scoping (automatic ComponentDialog owner)

Floating windows (Compose Dialog, ModalBottomSheet, and any window backed by ComponentDialog) automatically provide a NavigationEventDispatcherOwner. Don't manually re-provide LocalNavigationEventDispatcherOwner using CompositionLocalProvider inside dialogs.