public abstract class Navigator<D extends NavDestination>

Known direct subclasses
ActivityNavigator

ActivityNavigator implements cross-activity navigation.
DialogFragmentNavigator

Navigator that uses DialogFragment.show.
DynamicIncludeGraphNavigator

Navigator for include-dynamic.
FragmentNavigator

Navigator that navigates through fragment transactions.
NavGraphNavigator

A Navigator built specifically for NavGraph elements.
Known indirect subclasses
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 extends 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
public interface Navigator.Extras

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])
public annotation 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 NavigatorProvider.

Public constructors
<D extends NavDestination> Navigator()

Public methods
abstract @NonNull D

Construct a new NavDestination associated with this Navigator.
final boolean

Whether this Navigator is actively being used by a NavController.
void
navigate(
    @NonNull List<@NonNull NavBackStackEntry> entries,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination.
NavDestination
navigate(
    @NonNull D destination,
    SavedState args,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination.
void

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

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

Restore any state previously saved in onSaveState.
SavedState

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

Attempt to pop this navigator's back stack, performing the appropriate navigation.
void
popBackStack(@NonNull NavBackStackEntry popUpTo, boolean savedState)

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

Protected methods
final @NonNull NavigatorState

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

Public constructors

public <D extends NavDestination> Navigator()

Public methods

createDestination

Added in 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
@NonNull D

a new NavDestination

isAttached

Added in 2.4.0
public final boolean isAttached()

Whether this Navigator is actively being used by a NavController.

This is set to true when onAttach is called.

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

Parameters
@NonNull List<@NonNull NavBackStackEntry> entries

destination(s) to navigate to
NavOptions navOptions

additional options for navigation
Navigator.Extras navigatorExtras

extras unique to your Navigator.

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

Parameters
@NonNull D destination

destination node to navigate to
SavedState args

arguments to use for navigation
NavOptions navOptions

additional options for navigation
Navigator.Extras navigatorExtras

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
public void onAttach(@NonNull NavigatorState state)

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
public void onLaunchSingleTop(@NonNull NavBackStackEntry backStackEntry)

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

public void onRestoreState(@NonNull SavedState savedState)

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
@NonNull SavedState savedState

The state previously saved

onSaveState

Added in 1.0.0
public SavedState onSaveState()

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

popBackStack

Added in 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
public void popBackStack(@NonNull NavBackStackEntry popUpTo, boolean savedState)

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
@NonNull NavBackStackEntry popUpTo

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

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

Protected methods

getState

Added in 2.4.0
protected final @NonNull NavigatorState getState()

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