NavHostController

public final class NavHostController extends NavController

java.lang.Object
   ↳ androidx.navigation.NavController
     ↳ androidx.navigation.NavHostController
Known direct subclasses
TestNavHostController

Subclass of NavHostController that offers additional APIs for testing Navigation.

Subclass of NavController that offers additional APIs for use by a NavHost to connect the NavController to external dependencies.

Apps should generally not construct controllers, instead obtain a relevant controller directly from a navigation host via NavHost.navController or by using one of the utility methods on the Navigation class.

Summary

Public constructors

Public methods
final void
enableOnBackPressed(boolean enabled)

Set whether the NavController should handle the system Back button events via the registered OnBackPressedDispatcher.
final void

Sets the host's LifecycleOwner.
final void

Sets the host's OnBackPressedDispatcher.
final void

Sets the host's ViewModelStore used by the NavController to store ViewModels at the navigation graph level.

Inherited methods
From androidx.navigation.NavController
void

Adds an OnDestinationChangedListener to this controller to receive a callback whenever the currentDestination or its arguments change.
final boolean

Clears any saved state associated with KClass T that was previously saved via popBackStack when using a saveState value of true.
final boolean
@MainThread
clearBackStack(@IdRes int destinationId)

Clears any saved state associated with destinationId that was previously saved via popBackStack when using a saveState value of true.
final boolean

Clears any saved state associated with KClass route that was previously saved via popBackStack when using a saveState value of true.
final boolean
@MainThread
<T extends Object> clearBackStack(@NonNull T route)

Clears any saved state associated with KClass T that was previously saved via popBackStack when using a saveState value of true.
final boolean

Clears any saved state associated with route that was previously saved via popBackStack when using a saveState value of true.
@NonNull NavDeepLinkBuilder

Create a deep link to a destination within this NavController.
final @NonNull NavBackStackEntry
<T extends Object> getBackStackEntry()

Gets the topmost NavBackStackEntry for a route from KClass.
@NonNull NavBackStackEntry
getBackStackEntry(@IdRes int destinationId)

Gets the topmost NavBackStackEntry for a destination id.
final @NonNull NavBackStackEntry
<T extends Object> getBackStackEntry(@NonNull KClass<@NonNull T> route)

Gets the topmost NavBackStackEntry for a route from KClass.
final @NonNull NavBackStackEntry
<T extends Object> getBackStackEntry(@NonNull T route)

Gets the topmost NavBackStackEntry for a route from an Object.
final @NonNull NavBackStackEntry

Gets the topmost NavBackStackEntry for a route.
NavBackStackEntry

The topmost NavBackStackEntry.
final @NonNull Flow<@NonNull NavBackStackEntry>

A Flow that will emit the currently active NavBackStackEntry whenever it changes.
NavDestination

The current destination.
@NonNull NavGraph

The topmost navigation graph associated with this NavController.
@NonNull NavInflater

The inflater for this controller.
@NonNull NavigatorProvider

The NavController's NavigatorProvider.
NavBackStackEntry

The previous visible NavBackStackEntry.
@NonNull ViewModelStoreOwner
getViewModelStoreOwner(@IdRes int navGraphId)

Gets the ViewModelStoreOwner for a NavGraph.
final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>>

A StateFlow that will emit the currently visible NavBackStackEntries whenever they change.
boolean

Checks the given Intent for a Navigation deep link and navigates to the deep link if present.
final boolean

Checks the given NavDeepLinkRequest for a Navigation deep link and navigates to the destination if present.
void

Navigate to a destination via the given deep link Uri.
void
void

Navigate via the given NavDirections
void

Navigate to a destination via the given NavDeepLinkRequest.
void

Navigate to a destination from the current navigation graph.
void
@MainThread
navigate(@NonNull NavUri deepLink, NavOptions navOptions)

Navigate to a destination via the given deep link Uri.
void
@MainThread
navigate(@NonNull Uri deepLink, NavOptions navOptions)
void
@MainThread
navigate(@NonNull NavDirections directions, NavOptions navOptions)

Navigate via the given NavDirections
void
@MainThread
navigate(
    @NonNull NavDirections directions,
    @NonNull Navigator.Extras navigatorExtras
)

Navigate via the given NavDirections
void

Navigate to a destination via the given NavDeepLinkRequest.
void
@MainThread
navigate(@IdRes int resId, Bundle args)

Navigate to a destination from the current navigation graph.
final void
@MainThread
<T extends Object> navigate(
    @NonNull T route,
    @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder
)

Navigate to a route from an Object in the current NavGraph.
final void
@MainThread
navigate(
    @NonNull String route,
    @NonNull Function1<@NonNull NavOptionsBuilder, Unit> builder
)

Navigate to a route in the current NavGraph.
void
@MainThread
navigate(
    @NonNull NavUri deepLink,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination via the given deep link Uri.
void
@MainThread
navigate(
    @NonNull Uri deepLink,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)
void
@MainThread
navigate(
    @NonNull NavDeepLinkRequest request,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination via the given NavDeepLinkRequest.
void
@MainThread
navigate(@IdRes int resId, Bundle args, NavOptions navOptions)

Navigate to a destination from the current navigation graph.
final void
@MainThread
<T extends Object> navigate(
    @NonNull T route,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a route from an Object in the current NavGraph.
final void
@MainThread
navigate(
    @NonNull String route,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a route in the current NavGraph.
void
@MainThread
navigate(
    @IdRes int resId,
    Bundle args,
    NavOptions navOptions,
    Navigator.Extras navigatorExtras
)

Navigate to a destination from the current navigation graph.
boolean

Attempts to navigate up in the navigation hierarchy.
boolean

Attempts to pop the controller's back stack.
boolean
@MainThread
popBackStack(@IdRes int destinationId, boolean inclusive)

Attempts to pop the controller's back stack back to a specific destination.
final boolean
@MainThread
<T extends Object> popBackStack(boolean inclusive, boolean saveState)

Attempts to pop the controller's back stack back to a specific destination.
boolean
@MainThread
popBackStack(
    @IdRes int destinationId,
    boolean inclusive,
    boolean saveState
)

Attempts to pop the controller's back stack back to a specific destination.
final boolean
@MainThread
<T extends Object> popBackStack(
    @NonNull KClass<@NonNull T> route,
    boolean inclusive,
    boolean saveState
)

Attempts to pop the controller's back stack back to a specific destination.
final boolean
@MainThread
<T extends Object> popBackStack(
    @NonNull T route,
    boolean inclusive,
    boolean saveState
)

Attempts to pop the controller's back stack back to a specific destination.
final boolean
@MainThread
popBackStack(@NonNull String route, boolean inclusive, boolean saveState)

Attempts to pop the controller's back stack back to a specific destination.
void

Removes an OnDestinationChangedListener from this controller.
void
void

Restores all navigation controller state from a SavedState.
SavedState

Saves all navigation controller state to a SavedState.
void

The topmost navigation graph associated with this NavController.
void

Sets the navigation graph to the specified resource.
void
@MainThread
@CallSuper
setGraph(@NonNull NavGraph graph, Bundle startDestinationArgs)
void
@MainThread
@CallSuper
setGraph(@NonNull NavGraph graph, SavedState startDestinationArgs)

Sets the navigation graph to the specified graph.
void
@MainThread
@CallSuper
setGraph(@NavigationRes int graphResId, Bundle startDestinationArgs)

Sets the navigation graph to the specified resource.

Public constructors

Added in 2.1.0
public NavHostController(@NonNull Context context)
Parameters
@NonNull Context context

context for this controller

Public methods

enableOnBackPressed

Added in 2.1.0
public final void enableOnBackPressed(boolean enabled)

Set whether the NavController should handle the system Back button events via the registered OnBackPressedDispatcher.

Parameters
boolean enabled

True if the NavController should handle system Back button events.

setLifecycleOwner

Added in 2.1.0
public final void setLifecycleOwner(@NonNull LifecycleOwner owner)

Sets the host's LifecycleOwner.

Parameters
@NonNull LifecycleOwner owner

The LifecycleOwner associated with the containing NavHost.

setOnBackPressedDispatcher

Added in 2.1.0
public final void setOnBackPressedDispatcher(@NonNull OnBackPressedDispatcher dispatcher)

Sets the host's OnBackPressedDispatcher. If set, NavController will register a onBackPressedCallback to handle system Back button events.

You must explicitly called setLifecycleOwner before calling this method as the owner set there will be used as the LifecycleOwner for registering the onBackPressedCallback.

You can dynamically enable and disable whether the NavController should handle the system Back button events by calling enableOnBackPressed.

Parameters
@NonNull OnBackPressedDispatcher dispatcher

The OnBackPressedDispatcher associated with the containing NavHost.
Throws
kotlin.IllegalStateException

if you have not called setLifecycleOwner before calling this method.
See also
setLifecycleOwner

setViewModelStore

Added in 2.1.0
public final void setViewModelStore(@NonNull ViewModelStore viewModelStore)

Sets the host's ViewModelStore used by the NavController to store ViewModels at the navigation graph level. This is required to call getViewModelStoreOwner and should generally be called for you by your NavHost.

You must call this method before setGraph or similar methods, because the ViewModelStore set here will be used by the created NavBackStackEntry items.

Parameters
@NonNull ViewModelStore viewModelStore

ViewModelStore used to store ViewModels at the navigation graph level
Throws
kotlin.IllegalStateException

if this method is called when graph was already set via setGraph or similar methods.