# NavigationEventDispatcher

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

*** ** * ** ***

Common/AllAndroid/JVMJavaScript
- Cmn

  ```
  class NavigationEventDispatcher
  ```

*** ** * ** ***

A dispatcher for navigation events that can be organized hierarchically.

This class acts as a localized entry point for registering `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` instances and dispatching navigation events within a specific UI scope, such as a composable or a fragment.

Dispatchers can be linked in a parent-child hierarchy. This structure allows for a sophisticated system where nested UI components can handle navigation events independently while still respecting the state of their parent. The core logic is delegated to a single, shared `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventProcessor` instance across the entire hierarchy, ensuring consistent event handling.

It is important to call `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#dispose()` when the owner of this dispatcher is destroyed (e.g., in a `DisposableEffect`) to unregister handlers and prevent memory leaks.

## Summary

| ### Constants |
|---|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_DEFAULT() = 1` Default priority level for primary UI content. | Cmn |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_OVERLAY() = 0` Highest priority level, intended for overlay UI components. | Cmn |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#NavigationEventDispatcher()()` Creates a **root** `NavigationEventDispatcher` with no default fallback action. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#NavigationEventDispatcher(androidx.navigationevent.OnBackCompletedFallback)( onBackCompletedFallback: https://developer.android.com/reference/kotlin/androidx/navigationevent/OnBackCompletedFallback )` Creates a **root** `NavigationEventDispatcher` with a fallback action. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#NavigationEventDispatcher(androidx.navigationevent.NavigationEventDispatcher)(parent: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher)` Creates a **child** `NavigationEventDispatcher` linked to a parent. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#NavigationEventDispatcher(androidx.navigationevent.OnBackCompletedFallback,androidx.navigationevent.OnForwardCompletedFallback)( onBackCompletedFallback: https://developer.android.com/reference/kotlin/androidx/navigationevent/OnBackCompletedFallback, onForwardCompletedFallback: https://developer.android.com/reference/kotlin/androidx/navigationevent/OnForwardCompletedFallback )` Creates a **root** `NavigationEventDispatcher` with a back and forward fallback action. | Cmn |

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addHandler(androidx.navigationevent.NavigationEventHandler,kotlin.Int)(handler: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler<*>, priority: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Adds a new `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` to receive navigation events. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addInput(androidx.navigationevent.NavigationEventInput)(input: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput)` Adds an input with an unspecified priority, registering it with the shared processor and binding it to this dispatcher's lifecycle. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addInput(androidx.navigationevent.NavigationEventInput,kotlin.Int)(input: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput, priority: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Adds an input with a specific priority, registering it with the shared processor and binding it to this dispatcher's lifecycle. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#dispose()()` Removes this dispatcher and its entire chain of descendants from the hierarchy. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/MainThread https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#removeInput(androidx.navigationevent.NavigationEventInput)(input: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput)` Removes and detaches an input from this dispatcher and the shared processor. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHistory>` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#history()` The globally observable, read-only state of the navigation history stack. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#isEnabled()` Controls whether this dispatcher is active and will process navigation events. | Cmn |
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState>` | `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#transitionState()` The globally observable, read-only state of the physical navigation gesture. | Cmn |

## Constants

### PRIORITY_DEFAULT

Cmn

```
const val PRIORITY_DEFAULT = 1: Int
```

Default priority level for primary UI content.

Components at this level will receive navigation events after `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_OVERLAY()` components have been given a chance to handle them.

### PRIORITY_OVERLAY

Cmn

```
const val PRIORITY_OVERLAY = 0: Int
```

Highest priority level, intended for overlay UI components.

Components at this level (e.g., dialogs, bottom sheets, navigation drawers) will receive navigation events before components at `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_DEFAULT()`.

## Public constructors

### NavigationEventDispatcher

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

```
NavigationEventDispatcher()
```

Creates a **root** `NavigationEventDispatcher` with no default fallback action.

Establishes the top-level dispatcher for a new navigation hierarchy, typically within an `Activity` or a top-level composable. It creates its own internal `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventProcessor`.

If a navigation event completes without being handled by any registered `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler`, nothing further will happen.

### NavigationEventDispatcher

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

```
NavigationEventDispatcher(
    onBackCompletedFallback: OnBackCompletedFallback
)
```

Creates a **root** `NavigationEventDispatcher` with a fallback action.

Establishes the top-level dispatcher for a new navigation hierarchy, typically within an `Activity` or a top-level composable. It creates its own internal `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventProcessor`.

| Parameters |
|---|---|
| `onBackCompletedFallback: https://developer.android.com/reference/kotlin/androidx/navigationevent/OnBackCompletedFallback` | A lambda to be invoked if a navigation event **completes** and no registered `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` handles it. This provides a default "back" action for the entire hierarchy. **It will not be invoked if the event is cancelled.** |

### NavigationEventDispatcher

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

```
NavigationEventDispatcher(parent: NavigationEventDispatcher)
```

Creates a **child** `NavigationEventDispatcher` linked to a parent.

Used to create nested dispatchers within an existing hierarchy. The new dispatcher shares the same underlying `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventProcessor` as its parent, allowing it to participate in the same event stream.

| Parameters |
|---|---|
| `parent: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher` | The parent `NavigationEventDispatcher` to which this dispatcher will be attached. |

### NavigationEventDispatcher

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

```
NavigationEventDispatcher(
    onBackCompletedFallback: OnBackCompletedFallback,
    onForwardCompletedFallback: OnForwardCompletedFallback
)
```

Creates a **root** `NavigationEventDispatcher` with a back and forward fallback action.

Establishes the top-level dispatcher for a new navigation hierarchy, typically within an `Activity` or a top-level composable. It creates its own internal `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventProcessor`.

| Parameters |
|---|---|
| `onBackCompletedFallback: https://developer.android.com/reference/kotlin/androidx/navigationevent/OnBackCompletedFallback` | A lambda to be invoked if a back navigation event **completes** and no registered `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` handles it. This provides a default "back" action for the entire hierarchy. **It will not be invoked if the event is cancelled.** |
| `onForwardCompletedFallback: https://developer.android.com/reference/kotlin/androidx/navigationevent/OnForwardCompletedFallback` | A lambda to be invoked if a forward navigation event **completes** and no registered `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` handles it. This provides a default "forward" action for the entire hierarchy. **It will not be invoked if the event is cancelled.** |

## Public functions

### addHandler

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

```
@MainThread
fun addHandler(
    handler: NavigationEventHandler<*>,
    priority: Int = PRIORITY_DEFAULT
): Unit
```

Adds a new `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` to receive navigation events.

**Handlers are invoked based on `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addHandler(androidx.navigationevent.NavigationEventHandler,kotlin.Int)`, and then by recency.** All `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_OVERLAY()` handlers are called before any `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_DEFAULT()` handlers. Within each priority group, handlers are invoked in a Last-In, First-Out (LIFO) order---the most recently added handler is called first.

All handlers are invoked on the main thread. To stop receiving events, a handler must be removed via `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler#remove()`.

| Parameters |
|---|---|
| `handler: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler<*>` | The handler instance to be added. |
| `priority: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = PRIORITY_DEFAULT` | The priority of the handler, determining its invocation order relative to others. See `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher.Priority`. Value is one of the following: - `0` - `1` <br /> |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the given handler is already registered with a different dispatcher. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addHandler(androidx.navigationevent.NavigationEventHandler,kotlin.Int)` is not one of the supported constants. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the dispatcher has already been disposed. |

### addInput

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

```
@MainThread
fun addInput(input: NavigationEventInput): Unit
```

Adds an input with an unspecified priority, registering it with the shared processor and binding it to this dispatcher's lifecycle.

The input is registered globally with the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#sharedProcessor()` to receive system-wide state updates (e.g., whether any handlers are enabled). It is also tracked locally by this dispatcher for lifecycle management.

The input's `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onAdded(androidx.navigationevent.NavigationEventDispatcher)` method is invoked immediately upon addition. It will be automatically detached when this dispatcher `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#dispose()` is called.

| Parameters |
|---|---|
| `input: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput` | The input to add. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the dispatcher has already been disposed. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addInput(androidx.navigationevent.NavigationEventInput)` is already added to a dispatcher. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#removeInput(androidx.navigationevent.NavigationEventInput)` |   |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onRemoved()` |   |

### addInput

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

```
@MainThread
fun addInput(input: NavigationEventInput, priority: Int): Unit
```

Adds an input with a specific priority, registering it with the shared processor and binding it to this dispatcher's lifecycle.

The input is registered globally with the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#sharedProcessor()` to receive system-wide state updates (e.g., whether any handlers are enabled). It is also tracked locally by this dispatcher for lifecycle management.

The input's `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onAdded(androidx.navigationevent.NavigationEventDispatcher)` method is invoked immediately upon addition. It will be automatically detached when this dispatcher `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#dispose()` is called.

| Parameters |
|---|---|
| `input: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput` | The input to add. |
| `priority: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The priority to associate with this input. Must be one of the supported constants: `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_OVERLAY()`, `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_DEFAULT()`. Value is one of the following: - `0` - `1` <br /> |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the dispatcher has already been disposed. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addInput(androidx.navigationevent.NavigationEventInput,kotlin.Int)` is already added to a dispatcher. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addInput(androidx.navigationevent.NavigationEventInput,kotlin.Int)` is not one of the supported constants. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#removeInput(androidx.navigationevent.NavigationEventInput)` |   |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onRemoved()` |   |

### dispose

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

```
@MainThread
fun dispose(): Unit
```

Removes this dispatcher and its entire chain of descendants from the hierarchy.

This is the primary cleanup method and should be called when the component owning this dispatcher is destroyed (e.g., in `DisposableEffect` in Compose).

This is a **terminal** operation; once a dispatcher is disposed, it cannot be reused.

Calling this method triggers a comprehensive, iterative cleanup:

1. It iteratively processes and disposes of all child dispatchers and their descendants, ensuring a complete top-down cleanup of the entire sub-hierarchy without recursion.

2. For each dispatcher, it first detaches all registered `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput` instances by calling `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onRemoved()`. This severs their lifecycle link to the dispatcher and allows them to release any tied resources.

3. It then removes all `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler` instances registered with that dispatcher from the shared processor, preventing memory leaks.

4. Finally, it removes the dispatcher from its parent's list of children, fully dismantling the hierarchy.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the dispatcher has already been disposed. |

### removeInput

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

```
@MainThread
fun removeInput(input: NavigationEventInput): Unit
```

Removes and detaches an input from this dispatcher and the shared processor.

This severs the input's lifecycle link to the dispatcher. Its `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onRemoved()` method is invoked, and it will no longer receive lifecycle calls or global state updates from the processor.

| Parameters |
|---|---|
| `input: https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput` | The input to remove. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the dispatcher has already been disposed. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#addInput(androidx.navigationevent.NavigationEventInput)` |   |
| `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInput#onAdded(androidx.navigationevent.NavigationEventDispatcher)` |   |

## Public properties

### history

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

```
val history: StateFlow<NavigationEventHistory>
```

The globally observable, read-only state of the navigation history stack.

This flow represents *only* the navigation stack (the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHistory#mergedHistory()` and `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHistory#currentIndex()`) and is the counterpart to transition state.

A key contract of this state is that it remains **stable** during a navigation gesture. It only updates when the navigation stack itself changes (e.g., when a new handler becomes active, or the active handler's info is updated), which typically occurs *after* a gesture completes or *before* one begins.

This allows UI components to subscribe only to changes in the history stack without being notified of rapid gesture progress updates from transition state.

### isEnabled

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

```
var isEnabled: Boolean
```

Controls whether this dispatcher is active and will process navigation events.

A dispatcher's effective enabled state is hierarchical. It depends on both its own local `isEnabled` state and the state of its parent.

**Getting the value**:

- This will return `false` if the `parentDispatcher` exists and its `isEnabled` state is `false`, regardless of this dispatcher's own setting. This provides a simple way to disable an entire branch of a navigation hierarchy by disabling its root.

- If there is no parent or the parent is enabled, it will return the local value of this property (`true` by default).

**Setting the value**:

- This only updates the local enabled state for this specific dispatcher. The getter will always re-evaluate the effective state based on the parent.

For this dispatcher to be truly active, its local `isEnabled` property must be `true`, and the `isEnabled` properties of all its ancestors must also be `true`.

### transitionState

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

```
val transitionState: StateFlow<NavigationEventTransitionState>
```

The globally observable, read-only state of the physical navigation gesture.

This flow represents *only* the gesture's progress (e.g., `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState.Idle` or `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState.InProgress`) and is separate from the navigation history state.

System-level components or UI animations can subscribe to this flow to react to the start, progress, and end of a gesture without needing to know about the specific, generic `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventInfo` types involved in the history.

This state is derived from the `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState` of the currently active `https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler`.