# NavigationEventHandler

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

*** ** * ** ***

Common/AllAndroid/JVMJavaScript
- Cmn

  ```
  abstract class NavigationEventHandler<T : NavigationEventInfo>
  ```
Known direct subclasses [TestNavigationEventHandler](https://developer.android.com/reference/kotlin/androidx/navigationevent/testing/TestNavigationEventHandler)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/testing/TestNavigationEventHandler` | A test implementation of `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` that records received events and invocation counts. |

*** ** * ** ***

Base class for handling navigation gestures dispatched by a `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher`.

A `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` defines how an active component responds to system navigation gestures (such as predictive back) and exposes the directional context needed to represent the app's current navigation affordances:

- `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#backInfo()`: Contextual information describing what is available when navigating back.

- `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#currentInfo()`: The single active destination represented by this handler.

- `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#forwardInfo()`: Contextual information describing what is available when navigating forward.

Subclasses can override lifecycle methods (e.g., `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackStarted(androidx.navigationevent.NavigationEvent)`, `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackProgressed(androidx.navigationevent.NavigationEvent)`, `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackCompleted()`, `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackCancelled()`, and their forward equivalents) to respond to gesture progression and terminal outcomes.

A handler must be registered with a `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` to receive events. It will only be invoked while both the dispatcher and this handler are enabled.

| Parameters |
|---|---|
| `<T : https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo>` | The type of `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo` associated with this handler. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` |   |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput` |   |

## Summary

| ### Public constructors |
|---|---|
| `<T : https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo> https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#NavigationEventHandler(androidx.navigationevent.NavigationEventInfo,kotlin.Boolean)( initialInfo: T, isBackEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Creates a handler that is only enabled for back navigation gestures. | Cmn |
| `<T : https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo> https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#NavigationEventHandler(androidx.navigationevent.NavigationEventInfo,kotlin.Boolean,kotlin.Boolean)( initialInfo: T, isBackEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, isForwardEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` | Cmn |

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#remove()()` Removes this handler from the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` it is registered with. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)(currentInfo: T, backInfo: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>, forwardInfo: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>)` Sets the directional navigation context for this handler. | Cmn |

| ### Protected functions |
|---|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackCancelled()()` Override this to handle the cancellation of a back navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackCompleted()()` Override this to handle the completion of a back navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackProgressed(androidx.navigationevent.NavigationEvent)(event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent)` Override this to handle the progress of an ongoing back navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackStarted(androidx.navigationevent.NavigationEvent)(event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent)` Override this to handle the beginning of a back navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onForwardCancelled()()` Override this to handle the cancellation of a forward navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onForwardCompleted()()` Override this to handle the completion of a forward navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onForwardProgressed(androidx.navigationevent.NavigationEvent)(event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent)` Override this to handle the progress of an ongoing forward navigation event. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/EmptySuper https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onForwardStarted(androidx.navigationevent.NavigationEvent)(event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent)` Override this to handle the beginning of a forward navigation event. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#backInfo()` Contextual information describing the application's *back* state for this handler. | Cmn |
| `T` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#currentInfo()` The contextual information representing the active destination for this handler. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T>` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#forwardInfo()` Contextual information describing the application's *forward* state for this handler. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#isBackEnabled()` Controls whether this handler is active and should be considered for back event dispatching. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#isForwardEnabled()` Controls whether this handler is active and should be considered for forward event dispatching. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#transitionState()` The current transition state of this specific handler (e.g., `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState.Idle` or `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState.InProgress`). | Cmn |

## Public constructors

### NavigationEventHandler

Cmn

```
<T : NavigationEventInfo> NavigationEventHandler(
    initialInfo: T,
    isBackEnabled: Boolean
)
```

Creates a handler that is only enabled for back navigation gestures.

Forward navigation will be disabled by default.

| Parameters |
|---|---|
| `initialInfo: T` | The initial value for `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#currentInfo()`. |
| `isBackEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | If `true`, this handler will process back navigation gestures. |

### NavigationEventHandler

Cmn

```
<T : NavigationEventInfo> NavigationEventHandler(
    initialInfo: T,
    isBackEnabled: Boolean,
    isForwardEnabled: Boolean
)
```

| Parameters |
|---|---|
| `<T : https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo>` | The type of `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo` associated with this handler. |
| `initialInfo: T` | The initial value for `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#currentInfo()`. |
| `isBackEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | If `true`, this handler will process back navigation gestures. |
| `isForwardEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | If `true`, this handler will process forward navigation gestures. |

## Public functions

### remove

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
fun remove(): Unit
```

Removes this handler from the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` it is registered with. If the handler is not registered, this call does nothing.

### setInfo

Cmn

```
fun setInfo(
    currentInfo: T,
    backInfo: List<T> = emptyList(),
    forwardInfo: List<T> = emptyList()
): Unit
```

Sets the directional navigation context for this handler.

Updates the three pieces of contextual information used to describe navigation affordances:

- `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`: the active destination.

- `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`: contextual information for back navigation (nearest-first).

- `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`: contextual information for forward navigation (nearest-first).

The lists are app-defined `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo` values (e.g., titles or metadata) that help the UI present navigation affordances or previews. An empty list indicates no affordance in that direction.

| Parameters |
|---|---|
| `currentInfo: T` | The contextual information representing the active destination. |
| `backInfo: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T> = emptyList()` | Context describing what is available when navigating back (nearest-first). |
| `forwardInfo: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<T> = emptyList()` | Context describing what is available when navigating forward (nearest-first). |

## Protected functions

### onBackCancelled

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onBackCancelled(): Unit
```

Override this to handle the cancellation of a back navigation event.

This is called when the user cancels the navigation action, signaling that the UI should return to its original state.

### onBackCompleted

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onBackCompleted(): Unit
```

Override this to handle the completion of a back navigation event.

This is called when the user commits to the back navigation action, signaling that the navigation should be finalized.

The default implementation throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html`. Any handler that can be completed **must** override this method to handle the navigation.

### onBackProgressed

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onBackProgressed(event: NavigationEvent): Unit
```

Override this to handle the progress of an ongoing back navigation event.

This is called repeatedly during a gesture-driven back navigation to update the UI in real-time based on the user's input.

| Parameters |
|---|---|
| `event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` | The `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` containing progress information. |

### onBackStarted

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onBackStarted(event: NavigationEvent): Unit
```

Override this to handle the beginning of a back navigation event.

This is called when a user action initiates a back navigation. It's the ideal place to prepare UI elements for a transition.

| Parameters |
|---|---|
| `event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` | The `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` that triggered this handler. |

### onForwardCancelled

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onForwardCancelled(): Unit
```

Override this to handle the cancellation of a forward navigation event.

This is called when the user cancels the navigation action, signaling that the UI should return to its original state.

### onForwardCompleted

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onForwardCompleted(): Unit
```

Override this to handle the completion of a forward navigation event.

This is called when the user commits to the forward navigation action, signaling that the navigation should be finalized.

The default implementation throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html`. Any handler that can be completed **must** override this method to handle the navigation.

### onForwardProgressed

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onForwardProgressed(event: NavigationEvent): Unit
```

Override this to handle the progress of an ongoing forward navigation event.

This is called repeatedly during a gesture-driven forward navigation to update the UI in real-time based on the user's input.

| Parameters |
|---|---|
| `event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` | The `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` containing progress information. |

### onForwardStarted

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@EmptySuper
protected open fun onForwardStarted(event: NavigationEvent): Unit
```

Override this to handle the beginning of a forward navigation event.

This is called when a user action initiates a forward navigation. It's the ideal place to prepare UI elements for a transition.

| Parameters |
|---|---|
| `event: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` | The `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEvent` that triggered this handler. |

## Public properties

### backInfo

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
val backInfo: List<T>
```

Contextual information describing the application's *back* state for this handler.

This is **not** a back stack. Instead, it contains app-defined `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo` values (for example, titles or metadata) that help render back affordances in the UI. The list may be empty if no back navigation is possible in this scope.

### currentInfo

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
val currentInfo: T
```

The contextual information representing the active destination for this handler.

This is always a single value, provided by the currently active handler, and reflects the foreground navigation state at this point in time.

### forwardInfo

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
val forwardInfo: List<T>
```

Contextual information describing the application's *forward* state for this handler.

This is **not** a forward stack. Instead, it contains app-defined `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo` values that help render forward affordances in the UI. The list may be empty if no forward navigation is possible in this scope.

### isBackEnabled

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
var isBackEnabled: Boolean
```

Controls whether this handler is active and should be considered for back event dispatching.

A handler's effective enabled state is hierarchical; it is directly influenced by the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` it is registered with.

**Getting the value**:

- This will return `false` if the associated `dispatcher` exists and its `isEnabled` state is `false`, regardless of the handler's own local setting. This provides a powerful mechanism to disable a whole group of handlers at once by simply disabling their dispatcher.

- Otherwise, it returns the handler's own locally stored state.

**Setting the value**:

- This updates the local enabled state of the handler itself.

- More importantly, it immediately notifies the `dispatcher` (if one is attached) that its list of enabled handlers might have changed, prompting a re-evaluation. This ensures the system's state remains consistent and responsive to changes.

For a handler to be truly active, both its local `isEnabled` property and its dispatcher's `isEnabled` property must evaluate to `true`.

### isForwardEnabled

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
var isForwardEnabled: Boolean
```

Controls whether this handler is active and should be considered for forward event dispatching.

A handler's effective enabled state is hierarchical; it is directly influenced by the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` it is registered with.

**Getting the value**:

- This will return `false` if the associated `dispatcher` exists and its `isEnabled` state is `false`, regardless of the handler's own local setting.

- Otherwise, it returns the handler's own locally stored state.

**Setting the value**:

- This updates the local enabled state of the handler itself.

- It immediately notifies the `dispatcher` (if one is attached) that its list of enabled handlers might have changed, prompting a re-evaluation.

For a handler to be truly active for forward events, both its local `isForwardEnabled` property and its dispatcher's `isEnabled` property must evaluate to `true`.

### transitionState

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
val transitionState: NavigationEventTransitionState
```

The current transition state of this specific handler (e.g., `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState.Idle` or `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState.InProgress`).

This state is updated by the dispatcher *before* the corresponding `on...` lifecycle methods (e.g., `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#onBackStarted(androidx.navigationevent.NavigationEvent)`) are called.