# 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)

*** ** * ** ***

Common/AllAndroid/JVMJavaScript
- Cmn

  ```
  abstract class Navigator<D : NavDestination>
  ```
Known direct subclasses [ActivityNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/ActivityNavigator), [BottomSheetNavigator](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/BottomSheetNavigator), [ComposableFragmentNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/fragment/compose/ComposableFragmentNavigator), [ComposeNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/compose/ComposeNavigator), [DialogFragmentNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/fragment/DialogFragmentNavigator), [DialogNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/compose/DialogNavigator), [DynamicIncludeGraphNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/dynamicfeatures/DynamicIncludeGraphNavigator), [FragmentNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/fragment/FragmentNavigator), [NavGraphNavigator](https://developer.android.com/reference/kotlin/androidx/navigation/NavGraphNavigator), [WearNavigator](https://developer.android.com/reference/kotlin/androidx/wear/compose/navigation/WearNavigator)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation/ActivityNavigator` | ActivityNavigator implements cross-activity navigation. |
| `https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/BottomSheetNavigator` | Navigator that drives a `https://developer.android.com/reference/kotlin/androidx/compose/material/ModalBottomSheetState` for use of `https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/ModalBottomSheetLayout.composable#ModalBottomSheetLayout(androidx.compose.material.navigation.BottomSheetNavigator,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.unit.Dp,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Function0)`s with the navigation library. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/fragment/compose/ComposableFragmentNavigator` | This Navigator intercepts the inflation of `navigation` destinations in a Navigation with Fragment XML file, reusing the `android:name` field as the fully qualified name of the composable function to use as the contents of the inflated destination. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/compose/ComposeNavigator` | Navigator that navigates through `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable`s. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/fragment/DialogFragmentNavigator` | Navigator that uses `https://developer.android.com/reference/kotlin/androidx/fragment/app/DialogFragment#show(androidx.fragment.app.FragmentManager,java.lang.String)`. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/compose/DialogNavigator` | Navigator that navigates through `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable`s that will be hosted within a `https://developer.android.com/reference/kotlin/androidx/compose/ui/window/Dialog.composable#Dialog(kotlin.Function0,androidx.compose.ui.window.DialogProperties,kotlin.Function0)`. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/dynamicfeatures/DynamicIncludeGraphNavigator` | Navigator for `include-dynamic`. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/fragment/FragmentNavigator` | Navigator that navigates through `https://developer.android.com/reference/kotlin/androidx/fragment/app/FragmentTransaction`. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/NavGraphNavigator` | A Navigator built specifically for `https://developer.android.com/reference/kotlin/androidx/navigation/NavGraph` elements. |
| `https://developer.android.com/reference/kotlin/androidx/wear/compose/navigation/WearNavigator` | Navigator that navigates through `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable`s. |

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

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation/dynamicfeatures/DynamicActivityNavigator` | Dynamic feature navigator for Activity destinations. |
| `https://developer.android.com/reference/kotlin/androidx/navigation/dynamicfeatures/fragment/DynamicFragmentNavigator` | The `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator` that enables navigating to destinations within dynamic feature modules. |
| `https://developer.android.com/reference/kotlin/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/kotlin/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/kotlin/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/kotlin/androidx/navigation/Navigator.Name` to their class. Any custom attributes used by the associated `https://developer.android.com/reference/kotlin/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 : https://developer.android.com/reference/kotlin/androidx/navigation/NavDestination>` | the subclass of `https://developer.android.com/reference/kotlin/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 |
|---|
| `interface https://developer.android.com/reference/kotlin/androidx/navigation/Navigator.Extras` Interface indicating that this class should be passed to its respective `https://developer.android.com/reference/kotlin/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]) annotation https://developer.android.com/reference/kotlin/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/kotlin/androidx/navigation/NavigatorProvider`. |

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

| ### Public functions |
|---|---|---|
| `abstract D` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#createDestination()()` Construct a new NavDestination associated with this Navigator. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#navigate(kotlin.collections.List,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)( entries: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation/NavBackStackEntry>, navOptions: https://developer.android.com/reference/kotlin/androidx/navigation/NavOptions?, navigatorExtras: https://developer.android.com/reference/kotlin/androidx/navigation/Navigator.Extras? )` Navigate to a destination. | Cmn |
| `open https://developer.android.com/reference/kotlin/androidx/navigation/NavDestination?` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#navigate(androidx.navigation.NavDestination,androidx.savedstate.SavedState,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)( destination: D, args: https://developer.android.com/reference/kotlin/androidx/savedstate/SavedState?, navOptions: https://developer.android.com/reference/kotlin/androidx/navigation/NavOptions?, navigatorExtras: https://developer.android.com/reference/kotlin/androidx/navigation/Navigator.Extras? )` Navigate to a destination. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/CallSuper https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#onAttach(androidx.navigation.NavigatorState)(state: https://developer.android.com/reference/kotlin/androidx/navigation/NavigatorState)` Indicator that this Navigator is actively being used by a `https://developer.android.com/reference/kotlin/androidx/navigation/NavController`. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#onLaunchSingleTop(androidx.navigation.NavBackStackEntry)(backStackEntry: https://developer.android.com/reference/kotlin/androidx/navigation/NavBackStackEntry)` Informational callback indicating that the given `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#onLaunchSingleTop(androidx.navigation.NavBackStackEntry)` has been affected by a `https://developer.android.com/reference/kotlin/androidx/navigation/NavOptions#shouldLaunchSingleTop()` operation. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#onRestoreState(androidx.savedstate.SavedState)(savedState: https://developer.android.com/reference/kotlin/androidx/savedstate/SavedState)` Restore any state previously saved in `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#onSaveState()`. | Cmn |
| `open https://developer.android.com/reference/kotlin/androidx/savedstate/SavedState?` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#onSaveState()()` Called to ask for a `https://developer.android.com/reference/kotlin/androidx/savedstate/SavedState` representing the Navigator's state. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#popBackStack()()` Attempt to pop this navigator's back stack, performing the appropriate navigation. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#popBackStack(androidx.navigation.NavBackStackEntry,kotlin.Boolean)(popUpTo: https://developer.android.com/reference/kotlin/androidx/navigation/NavBackStackEntry, savedState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Attempt to pop this navigator's back stack, performing the appropriate navigation. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/navigation/Navigator#isAttached()` Whether this Navigator is actively being used by a `https://developer.android.com/reference/kotlin/androidx/navigation/NavController`. | Cmn |

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

## Public constructors

### Navigator

Cmn

```
<D : NavDestination> Navigator()
```

## Public functions

### createDestination

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

```
abstract fun createDestination(): D
```

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 |
|---|---|
| `D` | a new NavDestination |

### navigate

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

```
open fun navigate(
    entries: List<NavBackStackEntry>,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
): Unit
```

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/kotlin/androidx/navigation/NavController` will delegate to it when appropriate.

| Parameters |
|---|---|
| `entries: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation/NavBackStackEntry>` | destination(s) to navigate to |
| `navOptions: https://developer.android.com/reference/kotlin/androidx/navigation/NavOptions?` | additional options for navigation |
| `navigatorExtras: https://developer.android.com/reference/kotlin/androidx/navigation/Navigator.Extras?` | extras unique to your Navigator. |

### navigate

Cmn

```
open fun navigate(
    destination: D,
    args: SavedState?,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
): NavDestination?
```

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/kotlin/androidx/navigation/NavController` will delegate to it when appropriate.

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

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/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

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

```
@CallSuper
open fun onAttach(state: NavigatorState): Unit
```

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

### onLaunchSingleTop

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

```
open fun onLaunchSingleTop(backStackEntry: NavBackStackEntry): Unit
```

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

### onRestoreState

Cmn

```
open fun onRestoreState(savedState: SavedState): Unit
```

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

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

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

### onSaveState

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

```
open fun onSaveState(): SavedState?
```

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

### popBackStack

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

```
open fun popBackStack(): Boolean
```

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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `true` if pop was successful |

### popBackStack

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

```
open fun popBackStack(popUpTo: NavBackStackEntry, savedState: Boolean): Unit
```

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

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

| Parameters |
|---|---|
| `popUpTo: https://developer.android.com/reference/kotlin/androidx/navigation/NavBackStackEntry` | the entry that should be popped off the `https://developer.android.com/reference/kotlin/androidx/navigation/NavigatorState#backStack()` along with all entries above this entry. |
| `savedState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | whether any Navigator specific state associated with `https://developer.android.com/reference/kotlin/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/kotlin/androidx/navigation/Navigator#navigate(kotlin.collections.List,androidx.navigation.NavOptions,androidx.navigation.Navigator.Extras)` with `https://developer.android.com/reference/kotlin/androidx/navigation/NavOptions#shouldRestoreState()`. |

## Public properties

### isAttached

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

```
val isAttached: Boolean
```

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

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

## Protected properties

### state

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

```
protected val state: NavigatorState
```

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

It is the responsibility of the Navigator to call `https://developer.android.com/reference/kotlin/androidx/navigation/NavigatorState#push(androidx.navigation.NavBackStackEntry)` and `https://developer.android.com/reference/kotlin/androidx/navigation/NavigatorState#pop(androidx.navigation.NavBackStackEntry,kotlin.Boolean)` to in order to update the `https://developer.android.com/reference/kotlin/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/kotlin/androidx/navigation/Navigator#isAttached()` is `false` |