# NavigationEventHandler

Common/AllAndroid/JVMNative/C/iOS

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventHandler.composable#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)( state: https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState<https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo>, isForwardEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, onForwardCancelled: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, onForwardCompleted: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, isBackEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, onBackCancelled: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, onBackCompleted: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` A composable that handles navigation events using simple lambda handlers, driven by a manually hoisted `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState`. | Cmn |

## Functions

### NavigationEventHandler

Cmn Artifact: [androidx.navigationevent:navigationevent-compose](https://developer.android.com/jetpack/androidx/releases/navigationevent) [View Source](https://cs.android.com/search?q=file:androidx/navigationevent/compose/NavigationEventHandler.kt+function:NavigationEventHandler) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@Composable
fun NavigationEventHandler(
    state: NavigationEventState<NavigationEventInfo>,
    isForwardEnabled: Boolean = true,
    onForwardCancelled: () -> Unit = {},
    onForwardCompleted: () -> Unit = {},
    isBackEnabled: Boolean = true,
    onBackCancelled: () -> Unit = {},
    onBackCompleted: () -> Unit = {}
): Unit
```

A composable that handles navigation events using simple lambda handlers, driven by a manually hoisted `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState`.

This is the core implementation of the navigation event handler. This overload must be used when you need to hoist the `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState` (by calling `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/rememberNavigationEventState.composable#rememberNavigationEventState(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)` at a higher level). Hoisting is necessary when other composables need to react to the gesture's `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState` (held within the `state` object), for example, to drive custom animations.

## Precedence

When multiple `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventHandler.composable#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)` are present in the composition, the one that is composed *last* among all enabled handlers will be invoked.

## Usage

It is important to call this composable **unconditionally** . Use `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/package-summary#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)` and `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/package-summary#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)` to control whether the handler is active. This is preferable to conditionally calling `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventHandler.composable#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)` (e.g., inside an `if` block), as conditional calls can change the order of composition, leading to unpredictable behavior where different handlers are invoked after recomposition.

## Timing Consideration

There are cases where a predictive back or forward gesture may be dispatched within a rendering frame before the corresponding `enabled` flag is updated, which can cause unexpected behavior (see [b/375343407](https://issuetracker.google.com/375343407), [b/384186542](https://issuetracker.google.com/384186542)). For example, if `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/package-summary#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)` is set to `false`, a back gesture initiated in the same frame may still trigger this handler because the system sees the stale `true` value.

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState<https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo>` | The hoisted `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState` (returned from `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/rememberNavigationEventState.composable#rememberNavigationEventState(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`) to be registered. This object links this handler's callbacks to the unique handler instance that is producing the state. |
| `isForwardEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Controls whether forward navigation gestures are handled. |
| `onForwardCancelled: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Called if a forward navigation gesture is cancelled. |
| `onForwardCompleted: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Called when a forward navigation gesture completes. |
| `isBackEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Controls whether back navigation gestures are handled. |
| `onBackCancelled: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Called if a back navigation gesture is cancelled. |
| `onBackCompleted: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Called when a back navigation gesture completes. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | If the provided `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventState` is passed to multiple `https://developer.android.com/reference/kotlin/androidx/navigationevent/compose/NavigationEventHandler.composable#NavigationEventHandler(androidx.navigationevent.compose.NavigationEventState,kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function0)` Composable. Each handler must have its own unique state. |