abstract class Navigator<D : NavDestination>

Known direct subclasses
ActivityNavigator

ActivityNavigator implements cross-activity navigation.
BottomSheetNavigator

Navigator that drives a ModalBottomSheetState for use of ModalBottomSheetLayouts with the navigation library.
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.
ComposeNavigator

Navigator that navigates through Composables.
DialogFragmentNavigator

Navigator that uses DialogFragment.show.
DialogNavigator

Navigator that navigates through Composables that will be hosted within a Dialog.
DynamicIncludeGraphNavigator

Navigator for include-dynamic.
FragmentNavigator

Navigator that navigates through fragment transactions.
NavGraphNavigator

A Navigator built specifically for NavGraph elements.
WearNavigator

Navigator that navigates through Composables.
Known indirect subclasses
DynamicActivityNavigator

Dynamic feature navigator for Activity destinations.
DynamicFragmentNavigator

The Navigator that enables navigating to destinations within dynamic feature modules.
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 knows how to launch into destinations backed by activities using Context.startActivity.

Navigators should be able to manage their own back stack when navigating between two destinations that belong to that navigator. The NavController manages a back stack of navigators representing the current navigation stack across all navigators.

Each Navigator should add the Navigator.Name annotation to their class. Any custom attributes used by the associated destination subclass should have a name corresponding with the name of the Navigator, e.g., ActivityNavigator uses <declare-styleable name="ActivityNavigator">

Parameters
<D : NavDestination>

the subclass of 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 indicating that this class should be passed to its respective Navigator to enable Navigator specific behavior.
@Retention(value = AnnotationRetention.RUNTIME)
@Target(allowedTargets = [AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CLASS])
annotation Navigator.Name

This annotation should be added to each Navigator subclass to denote the default name used to register the Navigator with a NavigatorProvider.

Public constructors

Public functions
abstract D

Construct a new NavDestination associated with this Navigator.
open Unit
navigate(
    entries: List<NavBackStackEntry>,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination.
open NavDestination?
navigate(
    destination: D,
    args: SavedState?,
    navOptions: NavOptions?,
    navigatorExtras: Navigator.Extras?
)

Navigate to a destination.
open Unit

Indicator that this Navigator is actively being used by a NavController.
open Unit

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.
open Unit

Restore any state previously saved in onSaveState.
open SavedState?

Called to ask for a SavedState representing the Navigator's state.
open Boolean

Attempt to pop this navigator's back stack, performing the appropriate navigation.
open Unit
popBackStack(popUpTo: NavBackStackEntry, savedState: Boolean)

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

Public properties
Boolean

Whether this Navigator is actively being used by a NavController.

Protected properties
NavigatorState

The state of the Navigator is the communication conduit between the Navigator and the NavController that has called onAttach.

Public constructors

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

the subclass of 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.

Public functions

createDestination

Added in 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
Added in 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; NavController will delegate to it when appropriate.

Parameters
entries: List<NavBackStackEntry>

destination(s) to navigate to
navOptions: NavOptions?

additional options for navigation
navigatorExtras: Navigator.Extras?

extras unique to your Navigator.

 
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; NavController will delegate to it when appropriate.

Parameters
destination: D

destination node to navigate to
args: SavedState?

arguments to use for navigation
navOptions: NavOptions?

additional options for navigation
navigatorExtras: Navigator.Extras?

extras unique to your Navigator.
Returns
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
@CallSuper
open fun onAttach(state: NavigatorState): Unit

Indicator that this Navigator is actively being used by a NavController. This is called when the NavController's state is ready to be restored.

onLaunchSingleTop

Added in 2.4.0
open fun onLaunchSingleTop(backStackEntry: NavBackStackEntry): Unit

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation. The entry provided is a new NavBackStackEntry instance with all the previous state of the old entry and possibly new arguments.

onRestoreState

open fun onRestoreState(savedState: SavedState): Unit

Restore any state previously saved in onSaveState. This will be called before any calls to navigate or popBackStack.

Calls to createDestination should not be dependent on any state restored here as createDestination can be called before the state is restored.

Parameters
savedState: SavedState

The state previously saved

onSaveState

Added in 1.0.0
open fun onSaveState(): SavedState?

Called to ask for a SavedState representing the Navigator's state. This will be restored in onRestoreState.

popBackStack

Added in 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
Boolean

true if pop was successful

popBackStack

Added in 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 popUpTo should be popped off the back stack.

Parameters
popUpTo: NavBackStackEntry

the entry that should be popped off the NavigatorState.backStack along with all entries above this entry.
savedState: Boolean

whether any Navigator specific state associated with popUpTo should be saved to later be restored by a call to navigate with NavOptions.shouldRestoreState.

Public properties

isAttached

Added in 2.4.0
val isAttached: Boolean

Whether this Navigator is actively being used by a NavController.

This is set to true when onAttach is called.

Protected properties

state

Added in 2.4.0
protected val state: NavigatorState

The state of the Navigator is the communication conduit between the Navigator and the NavController that has called onAttach.

It is the responsibility of the Navigator to call NavigatorState.push and NavigatorState.pop to in order to update the NavigatorState.backStack at the appropriate times.

Throws
kotlin.IllegalStateException

if isAttached is false