Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

NavHostFragment

open class NavHostFragment : Fragment, NavHost
kotlin.Any
   ↳ androidx.fragment.app.Fragment
   ↳ androidx.navigation.fragment.NavHostFragment

NavHostFragment provides an area within your layout for self-contained navigation to occur.

NavHostFragment is intended to be used as the content area within a layout resource defining your app's chrome around it, e.g.:

<androidx.drawerlayout.widget.DrawerLayout
         xmlns:android="http://schemas.android.com/apk/res/android"
         xmlns:app="http://schemas.android.com/apk/res-auto"
         android:layout_width="match_parent"
         android:layout_height="match_parent">
     <fragment
             android:layout_width="match_parent"
             android:layout_height="match_parent"
             android:id="@+id/my_nav_host_fragment"
             android:name="androidx.navigation.fragment.NavHostFragment"
             app:navGraph="@navigation/nav_sample"
             app:defaultNavHost="true" />
     <android.support.design.widget.NavigationView
             android:layout_width="wrap_content"
             android:layout_height="match_parent"
             android:layout_gravity="start"/>
  </androidx.drawerlayout.widget.DrawerLayout>
  

Each NavHostFragment has a NavController that defines valid navigation within the navigation host. This includes the navigation graph as well as navigation state such as current location and back stack that will be saved and restored along with the NavHostFragment itself.

NavHostFragments register their navigation controller at the root of their view subtree such that any descendant can obtain the controller instance through the Navigation helper class's methods such as Navigation#findNavController(View). View event listener implementations such as android.view.View.OnClickListener within navigation destination fragments can use these helpers to navigate based on user interaction without creating a tight coupling to the navigation host.

Summary

Public constructors

NavHostFragment provides an area within your layout for self-contained navigation to occur.

Public methods

open static NavHostFragment
create(@NavigationRes graphResId: Int)

Create a new NavHostFragment instance with an inflated NavGraph resource.

open static NavHostFragment
create(@NavigationRes graphResId: Int, @Nullable startDestinationArgs: Bundle?)

Create a new NavHostFragment instance with an inflated NavGraph resource.

open static NavController
findNavController(@NonNull fragment: Fragment)

Find a NavController given a local Fragment.

NavController

Returns the navigation controller for this navigation host.

open Unit
onAttach(@NonNull context: Context)

open Unit
onCreate(@Nullable savedInstanceState: Bundle?)

open View?
onCreateView(@NonNull inflater: LayoutInflater, @Nullable container: ViewGroup?, @Nullable savedInstanceState: Bundle?)

open Unit
onInflate(@NonNull context: Context, @NonNull attrs: AttributeSet, @Nullable savedInstanceState: Bundle?)

open Unit
onPrimaryNavigationFragmentChanged(isPrimaryNavigationFragment: Boolean)

open Unit
onSaveInstanceState(@NonNull outState: Bundle)

open Unit
onViewCreated(@NonNull view: View, @Nullable savedInstanceState: Bundle?)

Protected methods

open Navigator<out FragmentNavigator.Destination!>

Create the FragmentNavigator that this NavHostFragment will use.

open Unit
onCreateNavController(@NonNull navController: NavController)

Callback for when the NavController is created.

Inherited functions

Public constructors

<init>

NavHostFragment()

NavHostFragment provides an area within your layout for self-contained navigation to occur.

NavHostFragment is intended to be used as the content area within a layout resource defining your app's chrome around it, e.g.:

<androidx.drawerlayout.widget.DrawerLayout
         xmlns:android="http://schemas.android.com/apk/res/android"
         xmlns:app="http://schemas.android.com/apk/res-auto"
         android:layout_width="match_parent"
         android:layout_height="match_parent">
     <fragment
             android:layout_width="match_parent"
             android:layout_height="match_parent"
             android:id="@+id/my_nav_host_fragment"
             android:name="androidx.navigation.fragment.NavHostFragment"
             app:navGraph="@navigation/nav_sample"
             app:defaultNavHost="true" />
     <android.support.design.widget.NavigationView
             android:layout_width="wrap_content"
             android:layout_height="match_parent"
             android:layout_gravity="start"/>
  </androidx.drawerlayout.widget.DrawerLayout>
  

Each NavHostFragment has a NavController that defines valid navigation within the navigation host. This includes the navigation graph as well as navigation state such as current location and back stack that will be saved and restored along with the NavHostFragment itself.

NavHostFragments register their navigation controller at the root of their view subtree such that any descendant can obtain the controller instance through the Navigation helper class's methods such as Navigation#findNavController(View). View event listener implementations such as android.view.View.OnClickListener within navigation destination fragments can use these helpers to navigate based on user interaction without creating a tight coupling to the navigation host.

Public methods

create

@NonNull open static fun create(@NavigationRes graphResId: Int): NavHostFragment

Create a new NavHostFragment instance with an inflated NavGraph resource.

Parameters
graphResId Int: resource id of the navigation graph to inflate
Return
NavHostFragment: a new NavHostFragment instance

create

@NonNull open static fun create(@NavigationRes graphResId: Int, @Nullable startDestinationArgs: Bundle?): NavHostFragment

Create a new NavHostFragment instance with an inflated NavGraph resource.

Parameters
graphResId Int: resource id of the navigation graph to inflate
startDestinationArgs Int: arguments to send to the start destination of the graph
Return
NavHostFragment: a new NavHostFragment instance

findNavController

@NonNull open static fun findNavController(@NonNull fragment: Fragment): NavController

Find a NavController given a local Fragment.

This method will locate the NavController associated with this Fragment, looking first for a NavHostFragment along the given Fragment's parent chain. If a NavController is not found, this method will look for one along this Fragment's view hierarchy as specified by Navigation#findNavController(View).

Parameters
fragment Fragment: the locally scoped Fragment for navigation
Return
NavController: the locally scoped NavController for navigating from this Fragment
Exceptions
IllegalStateException if the given Fragment does not correspond with a NavHost or is not within a NavHost.

getNavController

@NonNull fun getNavController(): NavController

Returns the navigation controller for this navigation host. This method will return null until this host fragment's onCreate(Bundle) has been called and it has had an opportunity to restore from a previous instance state.

Return
NavController: this host's navigation controller
Exceptions
IllegalStateException if called before onCreate(Bundle)

onAttach

@CallSuper open fun onAttach(@NonNull context: Context): Unit

onCreate

@CallSuper open fun onCreate(@Nullable savedInstanceState: Bundle?): Unit

onCreateView

@Nullable open fun onCreateView(@NonNull inflater: LayoutInflater, @Nullable container: ViewGroup?, @Nullable savedInstanceState: Bundle?): View?

onInflate

@CallSuper open fun onInflate(@NonNull context: Context, @NonNull attrs: AttributeSet, @Nullable savedInstanceState: Bundle?): Unit

onPrimaryNavigationFragmentChanged

@CallSuper open fun onPrimaryNavigationFragmentChanged(isPrimaryNavigationFragment: Boolean): Unit

onSaveInstanceState

@CallSuper open fun onSaveInstanceState(@NonNull outState: Bundle): Unit

onViewCreated

open fun onViewCreated(@NonNull view: View, @Nullable savedInstanceState: Bundle?): Unit

Protected methods

createFragmentNavigator

@NonNull protected open fun createFragmentNavigator(): Navigator<out FragmentNavigator.Destination!>

Deprecated: Use onCreateNavController(NavController)

Create the FragmentNavigator that this NavHostFragment will use. By default, this uses FragmentNavigator, which replaces the entire contents of the NavHostFragment.

This is only called once in onCreate(Bundle) and should not be called directly by subclasses.

Return
Navigator<out FragmentNavigator.Destination!>: a new instance of a FragmentNavigator

onCreateNavController

@CallSuper protected open fun onCreateNavController(@NonNull navController: NavController): Unit

Callback for when the NavController is created. If you support any custom destination types, their Navigator should be added here to ensure it is available before the navigation graph is inflated / set.

By default, this adds a FragmentNavigator.

This is only called once in onCreate(Bundle) and should not be called directly by subclasses.

Parameters
navController NavController: The newly created NavController.