# NavigatorState

Artifact: [androidx.navigation:navigation-common](https://developer.android.com/jetpack/androidx/releases/navigation) [View Source](https://cs.android.com/search?q=file:androidx/navigation/NavigatorState.kt+class:androidx.navigation.NavigatorState) Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

*** ** * ** ***


```
public abstract class NavigatorState
```

<br />

Known direct subclasses [TestNavigatorState](https://developer.android.com/reference/androidx/navigation/testing/TestNavigatorState)

|---|---|
| `https://developer.android.com/reference/androidx/navigation/testing/TestNavigatorState` | An implementation of `https://developer.android.com/reference/androidx/navigation/NavigatorState` that allows testing a `https://developer.android.com/reference/androidx/navigation/Navigator` in isolation (i.e., without requiring a `https://developer.android.com/reference/androidx/navigation/NavController`). |

*** ** * ** ***

The NavigatorState encapsulates the state shared between the `https://developer.android.com/reference/androidx/navigation/Navigator` and the `https://developer.android.com/reference/androidx/navigation/NavController`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#NavigatorState()()` |

| ### Public methods |
|---|---|
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#createBackStackEntry(androidx.navigation.NavDestination,androidx.savedstate.SavedState)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavDestination destination, https://developer.android.com/reference/androidx/savedstate/SavedState arguments )` Create a new `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` from a given `https://developer.android.com/reference/androidx/navigation/NavigatorState#createBackStackEntry(androidx.navigation.NavDestination,androidx.savedstate.SavedState)` and `https://developer.android.com/reference/androidx/navigation/NavigatorState#createBackStackEntry(androidx.navigation.NavDestination,androidx.savedstate.SavedState)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry>>` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#getBackStack()()` While the `https://developer.android.com/reference/androidx/navigation/NavController` is responsible for the combined back stack across all Navigators, this back stack is specifically the set of destinations associated with this Navigator. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Set.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry>>` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#getTransitionsInProgress()()` This is the set of currently running transitions. |
| `void` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry entry)` This removes the given `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` from the `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()`. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/CallSuper https://developer.android.com/reference/androidx/navigation/NavigatorState#onLaunchSingleTop(androidx.navigation.NavBackStackEntry)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry backStackEntry)` Informational callback indicating that the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#onLaunchSingleTop(androidx.navigation.NavBackStackEntry)` has been affected by a `https://developer.android.com/reference/androidx/navigation/NavOptions#shouldLaunchSingleTop()` operation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/CallSuper https://developer.android.com/reference/androidx/navigation/NavigatorState#onLaunchSingleTopWithTransition(androidx.navigation.NavBackStackEntry)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry backStackEntry )` Informational callback indicating that the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#onLaunchSingleTopWithTransition(androidx.navigation.NavBackStackEntry)` has been affected by a `https://developer.android.com/reference/androidx/navigation/NavOptions#shouldLaunchSingleTop()` operation. |
| `void` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#pop(androidx.navigation.NavBackStackEntry,kotlin.Boolean)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry popUpTo, boolean saveState)` Pop all destinations up to and including `https://developer.android.com/reference/androidx/navigation/NavigatorState#pop(androidx.navigation.NavBackStackEntry,kotlin.Boolean)`. |
| `void` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry popUpTo, boolean saveState)` Pops all destinations up to and including `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)`. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/CallSuper https://developer.android.com/reference/androidx/navigation/NavigatorState#prepareForTransition(androidx.navigation.NavBackStackEntry)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry entry)` This prepares the given `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` for transition. |
| `void` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#push(androidx.navigation.NavBackStackEntry)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry backStackEntry)` Adds the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#push(androidx.navigation.NavBackStackEntry)` to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()`. |
| `void` | `https://developer.android.com/reference/androidx/navigation/NavigatorState#pushWithTransition(androidx.navigation.NavBackStackEntry)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry backStackEntry)` Adds the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#pushWithTransition(androidx.navigation.NavBackStackEntry)` to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()`. |

## Public constructors

### NavigatorState

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public NavigatorState()
```

## Public methods

### createBackStackEntry

```
public abstract @NonNull NavBackStackEntry createBackStackEntry(
    @NonNull NavDestination destination,
    SavedState arguments
)
```

Create a new `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` from a given `https://developer.android.com/reference/androidx/navigation/NavigatorState#createBackStackEntry(androidx.navigation.NavDestination,androidx.savedstate.SavedState)` and `https://developer.android.com/reference/androidx/navigation/NavigatorState#createBackStackEntry(androidx.navigation.NavDestination,androidx.savedstate.SavedState)`.

### getBackStack

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>> getBackStack()
```

While the `https://developer.android.com/reference/androidx/navigation/NavController` is responsible for the combined back stack across all Navigators, this back stack is specifically the set of destinations associated with this Navigator.

Changing the back stack must be done via `https://developer.android.com/reference/androidx/navigation/NavigatorState#push(androidx.navigation.NavBackStackEntry)` and `https://developer.android.com/reference/androidx/navigation/NavigatorState#pop(androidx.navigation.NavBackStackEntry,kotlin.Boolean)`.

### getTransitionsInProgress

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public final @NonNull StateFlow<@NonNull Set<@NonNull NavBackStackEntry>> getTransitionsInProgress()
```

This is the set of currently running transitions. Use this set to retrieve the entry and call `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` once the transition is complete.

### markTransitionComplete

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public void markTransitionComplete(@NonNull NavBackStackEntry entry)
```

This removes the given `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` from the `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()`. This should be called in conjunction with `https://developer.android.com/reference/androidx/navigation/NavigatorState#pushWithTransition(androidx.navigation.NavBackStackEntry)` and `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` as those call are responsible for adding entries to `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()`.

This should also always be called in conjunction with `https://developer.android.com/reference/androidx/navigation/NavigatorState#prepareForTransition(androidx.navigation.NavBackStackEntry)` to ensure all `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` settle into the proper state.

Failing to call this method could result in entries being prevented from reaching their final `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State`}.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#pushWithTransition(androidx.navigation.NavBackStackEntry)` |   |
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` |   |

### onLaunchSingleTop

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
@CallSuper
public void onLaunchSingleTop(@NonNull NavBackStackEntry backStackEntry)
```

Informational callback indicating that the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#onLaunchSingleTop(androidx.navigation.NavBackStackEntry)` has been affected by a `https://developer.android.com/reference/androidx/navigation/NavOptions#shouldLaunchSingleTop()` operation.

Replaces the topmost entry with same id with the new `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry`

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry backStackEntry` | the `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` to replace the old Entry within the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()` |

### onLaunchSingleTopWithTransition

Added in [2.6.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.6.0)

```
@CallSuper
public void onLaunchSingleTopWithTransition(
    @NonNull NavBackStackEntry backStackEntry
)
```

Informational callback indicating that the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#onLaunchSingleTopWithTransition(androidx.navigation.NavBackStackEntry)` has been affected by a `https://developer.android.com/reference/androidx/navigation/NavOptions#shouldLaunchSingleTop()` operation. This also adds the given and previous entry to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()`. Added entries have their `https://developer.android.com/reference/androidx/lifecycle/Lifecycle` capped at `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#STARTED` until an entry is passed into the `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` callback, when they are allowed to go to `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#RESUMED` while previous entries have their `https://developer.android.com/reference/androidx/lifecycle/Lifecycle` held at `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#CREATED` until an entry is passed into the `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` callback, when they are allowed to go to `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#DESTROYED` and have their state cleared.

Replaces the topmost entry with same id with the new `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry`

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry backStackEntry` | the `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` to replace the old Entry within the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()` |

### pop

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public void pop(@NonNull NavBackStackEntry popUpTo, boolean saveState)
```

Pop all destinations up to and including `https://developer.android.com/reference/androidx/navigation/NavigatorState#pop(androidx.navigation.NavBackStackEntry,kotlin.Boolean)`. This will remove those destinations from the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()`, saving their state if `https://developer.android.com/reference/androidx/navigation/NavigatorState#pop(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` is `true`.

### popWithTransition

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public void popWithTransition(@NonNull NavBackStackEntry popUpTo, boolean saveState)
```

Pops all destinations up to and including `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)`. This also adds the given and incoming entry to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()`. Added entries have their `https://developer.android.com/reference/androidx/lifecycle/Lifecycle` held at `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#CREATED` until an entry is passed into the `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` callback, when they are allowed to go to `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#DESTROYED` and have their state cleared.

This will remove those destinations from the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()`, saving their state if `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` is `true`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()` |   |
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` |   |
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#pushWithTransition(androidx.navigation.NavBackStackEntry)` |   |

### prepareForTransition

Added in [2.6.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.6.0)

```
@CallSuper
public void prepareForTransition(@NonNull NavBackStackEntry entry)
```

This prepares the given `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` for transition. This should be called in conjunction with `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` as that is responsible for settling the `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` into its final state.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` |   |

### push

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public void push(@NonNull NavBackStackEntry backStackEntry)
```

Adds the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#push(androidx.navigation.NavBackStackEntry)` to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()`.

### pushWithTransition

Added in [2.4.0](https://developer.android.com/jetpack/androidx/releases/navigation#2.4.0)

```
public void pushWithTransition(@NonNull NavBackStackEntry backStackEntry)
```

Adds the given `https://developer.android.com/reference/androidx/navigation/NavigatorState#pushWithTransition(androidx.navigation.NavBackStackEntry)` to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()`. This also adds the given and previous entry to the `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()`. Added entries have their `https://developer.android.com/reference/androidx/lifecycle/Lifecycle` capped at `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#STARTED` until an entry is passed into the `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` callback, when they are allowed to go to `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#RESUMED`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#transitionsInProgress()` |   |
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#markTransitionComplete(androidx.navigation.NavBackStackEntry)` |   |
| `https://developer.android.com/reference/androidx/navigation/NavigatorState#popWithTransition(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` |   |