# Navigator

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

*** ** * ** ***

<br />

```
public abstract class Navigator<D extends NavDestination>
```

<br />

Known direct subclasses [ActivityNavigator](https://developer.android.com/reference/androidx/navigation/ActivityNavigator), [DialogFragmentNavigator](https://developer.android.com/reference/androidx/navigation/fragment/DialogFragmentNavigator), [DynamicIncludeGraphNavigator](https://developer.android.com/reference/androidx/navigation/dynamicfeatures/DynamicIncludeGraphNavigator), [FragmentNavigator](https://developer.android.com/reference/androidx/navigation/fragment/FragmentNavigator), [NavGraphNavigator](https://developer.android.com/reference/androidx/navigation/NavGraphNavigator)

|---|---|
| `https://developer.android.com/reference/androidx/navigation/ActivityNavigator` | ActivityNavigator implements cross-activity navigation. |
| `https://developer.android.com/reference/androidx/navigation/fragment/DialogFragmentNavigator` | Navigator that uses `https://developer.android.com/reference/androidx/fragment/app/DialogFragment#show(androidx.fragment.app.FragmentManager,java.lang.String)`. |
| `https://developer.android.com/reference/androidx/navigation/dynamicfeatures/DynamicIncludeGraphNavigator` | Navigator for `include-dynamic`. |
| `https://developer.android.com/reference/androidx/navigation/fragment/FragmentNavigator` | Navigator that navigates through `https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction`. |
| `https://developer.android.com/reference/androidx/navigation/NavGraphNavigator` | A Navigator built specifically for `https://developer.android.com/reference/androidx/navigation/NavGraph` elements. |

Known indirect subclasses [DynamicActivityNavigator](https://developer.android.com/reference/androidx/navigation/dynamicfeatures/DynamicActivityNavigator), [DynamicFragmentNavigator](https://developer.android.com/reference/androidx/navigation/dynamicfeatures/fragment/DynamicFragmentNavigator), [DynamicGraphNavigator](https://developer.android.com/reference/androidx/navigation/dynamicfeatures/DynamicGraphNavigator)

|---|---|
| `https://developer.android.com/reference/androidx/navigation/dynamicfeatures/DynamicActivityNavigator` | Dynamic feature navigator for Activity destinations. |
| `https://developer.android.com/reference/androidx/navigation/dynamicfeatures/fragment/DynamicFragmentNavigator` | The `https://developer.android.com/reference/androidx/navigation/Navigator` that enables navigating to destinations within dynamic feature modules. |
| `https://developer.android.com/reference/androidx/navigation/dynamicfeatures/DynamicGraphNavigator` | Navigator for graphs in dynamic feature modules. |

*** ** * ** ***

Navigator defines a mechanism for navigating within an app.

Each Navigator sets the policy for a specific type of navigation, e.g. [ActivityNavigator](https://developer.android.com/reference/androidx/navigation/ActivityNavigator) knows how to launch into `https://developer.android.com/reference/androidx/navigation/NavDestination` backed by activities using [startActivity](https://developer.android.com/reference/android/content/Context#startActivity(android.content.Intent)).

Navigators should be able to manage their own back stack when navigating between two destinations that belong to that navigator. The `https://developer.android.com/reference/androidx/navigation/NavController` manages a back stack of navigators representing the current navigation stack across all navigators.

Each Navigator should add the `https://developer.android.com/reference/androidx/navigation/Navigator.Name` to their class. Any custom attributes used by the associated `https://developer.android.com/reference/androidx/navigation/NavDestination` subclass should have a name corresponding with the name of the Navigator, e.g., [ActivityNavigator](https://developer.android.com/reference/androidx/navigation/ActivityNavigator) uses `<declare-styleable name="ActivityNavigator">`

| Parameters |
|---|---|
| `<D extends https://developer.android.com/reference/androidx/navigation/NavDestination>` | the subclass of `https://developer.android.com/reference/androidx/navigation/NavDestination` used with this Navigator which can be used to hold any special data that will be needed to navigate to that destination. Examples include information about an intent to navigate to other activities, or a fragment class name to instantiate and swap to a new fragment. |

## Summary

| ### Nested types |
|---|
| `public interface https://developer.android.com/reference/androidx/navigation/Navigator.Extras` Interface indicating that this class should be passed to its respective `https://developer.android.com/reference/androidx/navigation/Navigator` to enable Navigator specific behavior. |
| `@https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-retention/index.html(value = https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-annotation-retention/-r-u-n-t-i-m-e/index.html) @https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-target/index.html(allowedTargets = [https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-annotation-target/-a-n-n-o-t-a-t-i-o-n_-c-l-a-s-s/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-annotation-target/-c-l-a-s-s/index.html]) public annotation https://developer.android.com/reference/androidx/navigation/Navigator.Name` This annotation should be added to each Navigator subclass in Android to denote the default name used to register the Navigator with a `https://developer.android.com/reference/androidx/navigation/NavigatorProvider`. |

| ### Public constructors |
|---|
| `<D extends https://developer.android.com/reference/androidx/navigation/NavDestination> https://developer.android.com/reference/androidx/navigation/Navigator#Navigator()()` |

| ### Public methods |
|---|---|
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull D` | `https://developer.android.com/reference/androidx/navigation/Navigator#createDestination()()` Construct a new NavDestination associated with this Navigator. |
| `final boolean` | `https://developer.android.com/reference/androidx/navigation/Navigator#isAttached()()` Whether this Navigator is actively being used by a `https://developer.android.com/reference/androidx/navigation/NavController`. |
| `void` | `https://developer.android.com/reference/androidx/navigation/Navigator#navigate(kotlin.collections.List,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)( @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> entries, https://developer.android.com/reference/androidx/navigation/NavOptions navOptions, https://developer.android.com/reference/androidx/navigation/Navigator.Extras navigatorExtras )` Navigate to a destination. |
| `https://developer.android.com/reference/androidx/navigation/NavDestination` | `https://developer.android.com/reference/androidx/navigation/Navigator#navigate(androidx.navigation.NavDestination,androidx.savedstate.SavedState,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)( @https://developer.android.com/reference/androidx/annotation/NonNull D destination, https://developer.android.com/reference/androidx/savedstate/SavedState args, https://developer.android.com/reference/androidx/navigation/NavOptions navOptions, https://developer.android.com/reference/androidx/navigation/Navigator.Extras navigatorExtras )` Navigate to a destination. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/CallSuper https://developer.android.com/reference/androidx/navigation/Navigator#onAttach(androidx.navigation.NavigatorState)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavigatorState state)` Indicator that this Navigator is actively being used by a `https://developer.android.com/reference/androidx/navigation/NavController`. |
| `void` | `https://developer.android.com/reference/androidx/navigation/Navigator#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/Navigator#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/navigation/Navigator#onRestoreState(androidx.savedstate.SavedState)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/savedstate/SavedState savedState)` Restore any state previously saved in `https://developer.android.com/reference/androidx/navigation/Navigator#onSaveState()`. |
| `https://developer.android.com/reference/androidx/savedstate/SavedState` | `https://developer.android.com/reference/androidx/navigation/Navigator#onSaveState()()` Called to ask for a `https://developer.android.com/reference/androidx/savedstate/SavedState` representing the Navigator's state. |
| `boolean` | `https://developer.android.com/reference/androidx/navigation/Navigator#popBackStack()()` Attempt to pop this navigator's back stack, performing the appropriate navigation. |
| `void` | `https://developer.android.com/reference/androidx/navigation/Navigator#popBackStack(androidx.navigation.NavBackStackEntry,kotlin.Boolean)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry popUpTo, boolean savedState)` Attempt to pop this navigator's back stack, performing the appropriate navigation. |

| ### Protected methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavigatorState` | `https://developer.android.com/reference/androidx/navigation/Navigator#getState()()` The state of the Navigator is the communication conduit between the Navigator and the `https://developer.android.com/reference/androidx/navigation/NavController` that has called `https://developer.android.com/reference/androidx/navigation/Navigator#onAttach(androidx.navigation.NavigatorState)`. |

## Public constructors

### Navigator

```
public <D extends NavDestination> Navigator()
```

## Public methods

### createDestination

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

```
public abstract @NonNull D createDestination()
```

Construct a new NavDestination associated with this Navigator.

Any initialization of the destination should be done in the destination's constructor as it is not guaranteed that every destination will be created through this method.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull D` | a new NavDestination |

### isAttached

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

```
public final boolean isAttached()
```

Whether this Navigator is actively being used by a `https://developer.android.com/reference/androidx/navigation/NavController`.

This is set to `true` when `https://developer.android.com/reference/androidx/navigation/Navigator#onAttach(androidx.navigation.NavigatorState)` is called.

### navigate

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

```
public void navigate(
    @NonNull List<@NonNull NavBackStackEntry> entries,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)
```

Navigate to a destination.

Requests navigation to a given destination associated with this navigator in the navigation graph. This method generally should not be called directly; `https://developer.android.com/reference/androidx/navigation/NavController` will delegate to it when appropriate.

| Parameters |
|---|---|
| `@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> entries` | destination(s) to navigate to |
| `https://developer.android.com/reference/androidx/navigation/NavOptions navOptions` | additional options for navigation |
| `https://developer.android.com/reference/androidx/navigation/Navigator.Extras navigatorExtras` | extras unique to your Navigator. |

### navigate

```
public NavDestination navigate(
    @NonNull D destination,
    SavedState args,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)
```

Navigate to a destination.

Requests navigation to a given destination associated with this navigator in the navigation graph. This method generally should not be called directly; `https://developer.android.com/reference/androidx/navigation/NavController` will delegate to it when appropriate.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull D destination` | destination node to navigate to |
| `https://developer.android.com/reference/androidx/savedstate/SavedState args` | arguments to use for navigation |
| `https://developer.android.com/reference/androidx/navigation/NavOptions navOptions` | additional options for navigation |
| `https://developer.android.com/reference/androidx/navigation/Navigator.Extras navigatorExtras` | extras unique to your Navigator. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/navigation/NavDestination` | The NavDestination that should be added to the back stack or null if no change was made to the back stack (i.e., in cases of single top operations where the destination is already on top of the back stack). |

### onAttach

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

```
@CallSuper
public void onAttach(@NonNull NavigatorState state)
```

Indicator that this Navigator is actively being used by a `https://developer.android.com/reference/androidx/navigation/NavController`. This is called when the NavController's state is ready to be restored.

### onLaunchSingleTop

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

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

Informational callback indicating that the given `https://developer.android.com/reference/androidx/navigation/Navigator#onLaunchSingleTop(androidx.navigation.NavBackStackEntry)` has been affected by a `https://developer.android.com/reference/androidx/navigation/NavOptions#shouldLaunchSingleTop()` operation. The entry provided is a new `https://developer.android.com/reference/androidx/navigation/NavBackStackEntry` instance with all the previous state of the old entry and possibly new arguments.

### onRestoreState

```
public void onRestoreState(@NonNull SavedState savedState)
```

Restore any state previously saved in `https://developer.android.com/reference/androidx/navigation/Navigator#onSaveState()`. This will be called before any calls to `https://developer.android.com/reference/androidx/navigation/Navigator#navigate(kotlin.collections.List,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)` or `https://developer.android.com/reference/androidx/navigation/Navigator#popBackStack(androidx.navigation.NavBackStackEntry,kotlin.Boolean)`.

Calls to `https://developer.android.com/reference/androidx/navigation/Navigator#createDestination()` should not be dependent on any state restored here as `https://developer.android.com/reference/androidx/navigation/Navigator#createDestination()` can be called before the state is restored.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/savedstate/SavedState savedState` | The state previously saved |

### onSaveState

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

```
public SavedState onSaveState()
```

Called to ask for a `https://developer.android.com/reference/androidx/savedstate/SavedState` representing the Navigator's state. This will be restored in `https://developer.android.com/reference/androidx/navigation/Navigator#onRestoreState(androidx.savedstate.SavedState)`.

### popBackStack

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

```
public boolean popBackStack()
```

Attempt to pop this navigator's back stack, performing the appropriate navigation.

Implementations should return `true` if navigation was successful. Implementations should return `false` if navigation could not be performed, for example if the navigator's back stack was empty.

| Returns |
|---|---|
| `boolean` | `true` if pop was successful |

### popBackStack

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

```
public void popBackStack(@NonNull NavBackStackEntry popUpTo, boolean savedState)
```

Attempt to pop this navigator's back stack, performing the appropriate navigation.

All destinations back to `https://developer.android.com/reference/androidx/navigation/Navigator#popBackStack(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` should be popped off the back stack.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigation/NavBackStackEntry popUpTo` | the entry that should be popped off the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()` along with all entries above this entry. |
| `boolean savedState` | whether any Navigator specific state associated with `https://developer.android.com/reference/androidx/navigation/Navigator#popBackStack(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` should be saved to later be restored by a call to `https://developer.android.com/reference/androidx/navigation/Navigator#navigate(kotlin.collections.List,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)` with `https://developer.android.com/reference/androidx/navigation/NavOptions#shouldRestoreState()`. |

## Protected methods

### getState

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

```
protected final @NonNull NavigatorState getState()
```

The state of the Navigator is the communication conduit between the Navigator and the `https://developer.android.com/reference/androidx/navigation/NavController` that has called `https://developer.android.com/reference/androidx/navigation/Navigator#onAttach(androidx.navigation.NavigatorState)`.

It is the responsibility of the Navigator to call `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)` to in order to update the `https://developer.android.com/reference/androidx/navigation/NavigatorState#backStack()` at the appropriate times.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/androidx/navigation/Navigator#isAttached()` is `false` |