The Navigation Architecture Component simplifies implementing navigation, while also helping you visualize your app's navigation flow. The library provides a number of benefits, including:

What you'll build

In this codelab, you will work with the sample app seen below:

All the activities and fragments have already been created for you. You will use the Navigation Component to connect them and in doing so, implement the following:

Prerequisites

Get the Code

Clone the navigation codelab from GitHub:

$ git clone https://github.com/googlecodelabs/android-navigation

Alternatively you can download the repository as a Zip file:

Download Zip

Get Android Studio 3.2 or higher

Make sure you are using Android Studio 3.2 or higher. This is required for the Android Studio navigation tooling.

If you need to download a recent version of Android Studio, you can do so here.

Enable Navigation on 3.2

The navigation editor is a standard part of Android Studio 3.3 and higher. If you're using Android Studio 3.2, navigation is an experimental feature and you'll need to enable it:

  1. Click File > Settings (Android Studio > Preferences on Mac)
  2. Select the Experimental category in the left pane
  3. Check Enable Navigation Editor
  4. Restart Android Studio

Overview of Navigation

The Navigation Component consists of three key parts, working together in harmony. They are:

  1. Navigation Graph (New XML resource) - This is a resource that contains all navigation-related information in one centralized location. This includes all the places in your app, known as destinations, and possible paths a user could take through your app.
  2. NavHostFragment (Layout XML view) - This is a special widget you add to your layout. It displays different destinations from your Navigation Graph.
  3. NavController (Kotlin/Java object) - This is an object that keeps track of the current position within the navigation graph. It orchestrates swapping destination content in the NavHostFragment as you move through a navigation graph.

When you navigate, you'll use the NavController object, telling it where you want to go or what path you want to take in your Navigation Graph. The NavController will then show the appropriate destination in the NavHostFragment.

That's the basic idea. Let's see what this looks like in practice, starting with the new Navigation Graph resource.

Destinations

The Navigation Component introduces the concept of a destination. A destination is any place you can navigate to in your app, usually a fragment or an activity. These are supported out of the box, but you can also make your own custom destination types if needed.

Navigation Graph

A navigation graph is a new resource type that defines all the possible paths a user can take through an app. It shows visually all the destinations that can be reached from a given destination. Android Studio displays the graph in its Navigation Editor. Here's part of the starting navigation graph you'll create for your app:

Exploring the Navigation Editor

1. Open res/navigation/mobile_navigation.xml

2. Click Design to go into Design mode:

Here's what you should see:

The navigation graph shows the available destinations. The arrows between the destinations are called actions. You'll learn more about actions later.

3. Click on a destination to see its attributes.

4. Click on any action, represented by an arrow, to see its attributes.

Anatomy of a navigation XML file

All of the changes you make in the graphical Navigation Editor change the underlying XML file, similar to the way the Layout Editor modifies the layout XML.

Click the Text tab:

You'll see some XML like this:

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
            xmlns:app="http://schemas.android.com/apk/res-auto"
            xmlns:tools="http://schemas.android.com/tools"
    app:startDestination="@+id/home_dest">

    <!-- ...tags for fragments and activities here -->

</navigation>

Notice:

Let's take a look at a fragment destination:

<fragment
    android:id="@+id/flow_step_one_dest"
    android:name="com.example.android.codelabs.navigation.FlowStepFragment"
    tools:layout="@layout/flow_step_one_fragment">
    <argument
        .../>

    <action
        android:id="@+id/next_action"
        app:destination="@+id/flow_step_two_dest">
    </action>
</fragment>

Notice:

Some <fragment> tags also contain <action>, <argument>, and <deepLink>, all of which we'll cover later.

The sample app starts with a few destinations in the graph. In this step, you'll add a brand new destination! You must add a destination to the navigation graph before you can navigate to it.

1. Open res/navigation/mobile_navigation.xml, and click the Design tab.

2. Click the New Destination icon, and select "settings_fragment"

The result is a new destination, which renders a preview of the fragment's layout in the design view.

Note that you can also edit the XML file directly to add destinations:

mobile_navigation.xml

<fragment
    android:id="@+id/settings_dest"
    android:name="com.example.android.codelabs.navigation.SettingsFragment"
    android:label="@string/settings"
    tools:layout="@layout/settings_fragment" />

Right now you have this awesome navigation graph, but you're not actually using it to navigate.

Activities and Navigation

The Navigation component follows the guidance outlined in the Principles of Navigation. The Principles of Navigation recommend you use activities as entry points for your app. Activities will also contain global navigation, such as the bottom nav,

In comparison, fragments will be the actual destination-specific layouts.

To get this all to work, you need to modify your activity layouts to contain a special widget called a NavHostFragment. A NavHostFragment swaps different fragment destinations in and out as you navigate through the navigation graph.

A simple layout supporting navigation similar to the picture above looks like this:

<LinearLayout
    .../>
    <androidx.appcompat.widget.Toolbar
        .../>
    <fragment
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1"
        android:id="@+id/my_nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        app:navGraph="@navigation/mobile_navigation"
        app:defaultNavHost="true"
        />
    <com.google.android.material.bottomnavigation.BottomNavigationView
        .../>
</LinearLayout>

Notice:

NavController

Finally, when a user does something like clicking a button, you need to trigger a navigate command. A special class called the NavController is what triggers the fragment swaps in the NavHostFragment.

// Command to navigate to flow_step_one_dest
findNavController().navigate(R.id.flow_step_one_dest)

Note that you pass in either a destination or action ID to navigate. These are the IDs defined in the navigation graph XML. This is an example of passing in a destination ID.

NavController is powerful because when you call methods like navigate() or popBackStack(), it translates these commands into the appropriate framework operations based on the type of destination you are navigating to or from. For example, when you call navigate() with an activity destination, the NavController calls startActivity() on your behalf.

There are a few ways to get a NavController object associated with your NavHostFragment. In Kotlin, it's recommended you use one of the following extension functions, depending on whether you're calling the navigation command from within a fragment, activity or view:

Navigate to a Destination with NavController

It's your turn to navigate using NavController. You'll hook up the Navigate To Destination button to navigate to the flow_step_one_dest destination (which is a destination that is a FlowStepFragment):

1. Open HomeFragment.kt

2. Hook up the navigate_destination_button in onViewCreated()

HomeFragment.kt

val button = view.findViewById<Button>(R.id.navigate_destination_button)
button?.setOnClickListener {
    findNavController().navigate(R.id.flow_step_one_dest)
}

3. Run the app and click the Navigate To Destination button. Note that the button navigates to the flow_step_one_dest destination.

The click listener code would look like this:

val button = view.findViewById<Button>(R.id.navigate_destination_button)
button?.setOnClickListener(
        Navigation.createNavigateOnClickListener(R.id.flow_step_one_dest, null)
)

Each navigate() call has a not very exciting default transition associated with it, as seen below:



The default transition, as well as other attributes associated with the call, can be overridden by including a set of NavOptions. NavOptions uses a Builder pattern which allows you to override and set only the options you need. There's also a ktx DSL for NavOptions, which is what you'll be using.

For animated transitions, you can define XML animation resources in the anim resource folder and then use those animations for transitions. Some examples are included in the app code:

Add a Custom Transition

Update the code so that pressing the Navigate To Destination button shows a custom transition animation.

1. Open HomeFragment.kt

2. Define a NavOptions and pass it into the navigate() call to navigate_destination_button

val options = navOptions {
    anim {
        enter = R.anim.slide_in_right
        exit = R.anim.slide_out_left
        popEnter = R.anim.slide_in_left
        popExit = R.anim.slide_out_right
    }
}
view.findViewById<Button>(R.id.navigate_destination_button)?.setOnClickListener {
    findNavController().navigate(R.id.flow_step_one_dest, null, options)
}

3. Remove the code added in step 5, if it's still there

4. Verify that tapping the Navigate To Destination button causes the fragment to slide onto the screen and that pressing back causes it to slide off the screen

Actions

The navigation system also allows you to navigate via actions. As previously mentioned, the lines shown in the navigation graph are visual representations of actions.

Navigation by actions has the following benefits over navigation by destination:

Here's the visual and XML for the action that connects flow_step_one_dest and flow_step_two_dest:

<fragment
    android:id="@+id/flow_step_one_dest"
    android:name="com.example.android.codelabs.navigation.FlowStepFragment">

    <argument
        .../>

    <action
        android:id="@+id/next_action"
        app:destination="@+id/flow_step_two_dest">
    </action>
</fragment>

<fragment
    android:id="@+id/flow_step_two_dest"
    android:name="com.example.android.codelabs.navigation.FlowStepFragment">
    <!-- ...removed for simplicity-->
</fragment>

Notice:

Here is another example, of the action connecting flow_step_two_dest to home_dest:

<fragment
    android:id="@+id/home_dest"
    android:name="com.example.android.codelabs.navigation.HomeFragment"
    .../>

<fragment
    android:id="@+id/flow_step_two_dest"
    android:name="com.example.android.codelabs.navigation.FlowStepFragment">

    <argument
        .../>

    <action
        android:id="@+id/next_action"
        app:popUpTo="@id/home_dest">
    </action>
</fragment>

Notice:

Navigate with an Action

Time to hook up the Navigate with Action button so that it lives up to its name!

1. Open the mobile_navigation.xml file in Design mode

2. Drag an arrow from home_dest to flow_step_one_dest:

3. With the action arrow selected (blue) change the properties of the action so that:

4. Click the Text tab

Note the newly added next_action action under the home_dest destination:

mobile_navigation.xml

<fragment android:id="@+id/home_dest"
        ...>
        
        <action android:id="@+id/next_action"
            app:destination="@+id/flow_step_one"
            app:enterAnim="@anim/slide_in_right"
            app:exitAnim="@anim/slide_out_left"
            app:popEnterAnim="@anim/slide_in_left"
            app:popExitAnim="@anim/slide_out_right" />

5. Open HomeFragment.kt

6. Add a click listener to the navigate_action_button

HomeFragment.kt

 view.findViewById<Button>(R.id.navigate_action_button)?.setOnClickListener(
        Navigation.createNavigateOnClickListener(R.id.next_action, null)
)

7. Verify that tapping the Navigate To Action now navigates to the next screen.

Safe Args

The navigation component has a Gradle plugin, called safe args, that generates simple object and builder classes for type-safe access to arguments specified for destinations and actions.

Safe args allows you to get rid of code like this when passing values between destinations:

val username = arguments?.getString("usernameKey")

And, instead, replace it with code that has generated setters and getters.

val username = args.username

Pass a value using safe args

1. Open the app/build.gradle file and notice the applied plugin:

app/build.gradle

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'androidx.navigation.safeargs'

android { 
   //...
}

2. Open mobile_navigation.xml, and notice how arguments are defined in the flow_step_one_dest destination.

mobile_navigation.xml

<fragment
    android:id="@+id/flow_step_one_dest"
    android:name="com.example.android.codelabs.navigation.FlowStepFragment"
    tools:layout="@layout/flow_step_one_fragment">
    <argument
        android:name="flowStepNumber"
        app:argType="integer"
        android:defaultValue="1"/>

    <action...>
    </action>
</fragment>

Using the <argument> tag, safeargs generates a class called FlowStepFragmentArgs.

Since the XML includes an argument called flowStepNumber, specified by android:name="flowStepNumber", the generated class FlowStepFragmentArgs will include a variable flowStepNumber with getters and setters.

3. Open FlowStepFragment.kt

4. Comment out the line of code shown below:

FlowStepFragment.kt

// Comment out this line
// val flowStepNumber = arguments?.getInt("flowStepNumber")

This old-style code is not type-safe. It's better to use safe args.

5. Update FlowStepFragment to use the code generated class FlowStepFragmentArgs. This will get the FlowStepFragment arguments in a type-safe manner:

FlowStepFragment.kt

val safeArgs = FlowStepFragmentArgs.fromBundle(arguments)
val flowStepNumber = safeArgs.flowStepNumber

Safe Args Direction classes

You can also use safe args to navigate in a type safe way, with or without adding arguments. You do this using the generated Directions classes.

Directions classes are generated for every distinct destination with actions. The Directions class includes methods for every action a destination has.

For example, the navigate_action_button click listener in HomeFragment.kt could be changed to:

HomeFragment.kt

// Note the usage of curly braces since we are defining the click listener lambda
view.findViewById<Button>(R.id.navigate_action_button)?.setOnClickListener{
    val action = HomeFragmentDirections.nextAction()
    action.setFlowStepNumber(1)
    findNavController().navigate(action)
}

NavigationUI and navigation-ui-ktx

The Navigation Components include a NavigationUI class and the navigation-ui-ktx kotlin extensions. NavigationUI has static methods that associate menu items with navigation destinations, and navigation-ui-ktx is a set of extension functions that do the same. If NavigationUI finds a menu item with the same ID as a destination on the current graph, it configures the menu item to navigate to that destination.

Using NavigationUI with an Options menu

One of the easiest ways to use NavigationUI is to have it simplify option menu setup. In particular, NavigationUI simplifies handling the onOptionsItemSelected callback.

1. Open MainActivity.kt

Notice how you already have the code for inflating the menu overflow_menu in onCreateOptionsMenu

2. Open res/menu/overflow_menu.xml

3. Update your overflow menu to include the settings_dest

overflow_menu.xml

<item
    android:id="@+id/settings_dest"
    android:icon="@drawable/ic_settings"
    android:menuCategory="secondary"
    android:title="@string/settings" />

4. Open MainActivity.kt

5. Have NavigationUI handle onOptionsItemSelected with the onNavDestinationSelected helper method. If the menu item is not meant to navigate, handle with super.onOptionsItemSelected

MainActivity.kt

override fun onOptionsItemSelected(item: MenuItem): Boolean {
    return item.onNavDestinationSelected(findNavController(R.id.my_nav_host_fragment))
            || super.onOptionsItemSelected(item)
}

6. Run your app. You should have a functional ActionBar menu that navigates to the SettingsFragment.

Using NavigationUI to configure Bottom Navigation

The code already contains the XML layout code for implementing bottom navigation, which is why you see the bottom navigation bar. But it doesn't navigate anywhere.

1. Open res/layout/navigation_activity/navigation_activity.xml (h470dp) and click the Text tab

Notice how the XML layout code for bottom navigation is there and refers to bottom_nav_menu.xml

navigation_activity.xml (h470dp)

<com.google.android.material.bottomnavigation.BottomNavigationView
    android:id="@+id/bottom_nav_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:menu="@menu/bottom_nav_menu" />

2. Open res/menu/bottom_nav_menu.xml

Notice how there are two items for the bottom navigation and that their ids match the destinations of navigation graph destinations

bottom_nav_menu.xml

<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item
        android:id="@id/home_dest"
        android:icon="@drawable/ic_home"
        android:title="@string/home" />
    <item
        android:id="@id/deeplink_dest"
        android:icon="@drawable/ic_android"
        android:title="@string/deeplink" />
</menu>

Let's make the bottom navigation actually do something using NavigationUI.

3. Open MainActivity.kt

4. Implement the setupBottomNavMenu method using setupWithNavController(bottomNavigationView: BottomNavigationView, navController: NavController)

MainActivity.kt

private fun setupBottomNavMenu(navController: NavController) {
    val bottomNav = findViewById<BottomNavigationView>(R.id.bottom_nav_view)
    bottomNav?.setupWithNavController(navController)
}

Now your bottom navigation works!

Using NavigationUI to configure a Navigation Drawer

Finally, let's use NavigationUI to configure the side navigation and navigation drawer, including handling the ActionBar and proper up navigation. You'll see this if you've got a large enough screen or if the screen's too short for bottom navigation.

First observe how the proper layout XML code is already in the app.

1. Open both navigation_activity.xml and navigation_activity.xml (w960dp)

Notice how both layouts contain a NavigationView connected to nav_drawer_menu. In the tablet version (w960dp) the NavigationView is always on screen. On smaller devices the NavigationView is nested within a DrawerLayout.

Now to start implementing the NavigationView navigation.

2. Open MainActivity.kt

3. Implement the setupNavigationMenu method using setupWithNavController(navigationView: NavigationView, navController: NavController). Notice how this version of the method takes a NavigationView and not a BottomNavigationView.

MainActivity.kt

private fun setupNavigationMenu(navController: NavController) {
    val sideNavView = findViewById<NavigationView>(R.id.nav_view)
    sideNavView?.setupWithNavController(navController)
}

Now the navigation view menu will show on the screen, but it will not affect the ActionBar.

Setting up the ActionBar requires creating an instance of AppBarConfiguration. The purpose of AppBarConfiguration is to specify the configuration options you want for your toolbars, collapsing toolbars, and action bars. Configuration options include whether the bar must handle a drawer layout and which destinations are considered top-level destinations.

Top-level destinations are the root-level destinations of your app. These destinations do not display an "up" button in the app bar, and they display the drawer icon if the destination uses a drawer layout.

4. Create an AppBarConfiguration by passing in a set of top-level destination IDs and the drawer layout.

MainActivity.kt

val drawerLayout : DrawerLayout? = findViewById(R.id.drawer_layout)
appBarConfiguration = AppBarConfiguration(
        setOf(R.id.home_dest, R.id.deeplink_dest),
        drawerLayout)

Now that you have an AppBarConfiguration, you can call NavigationUI.setupActionBarWithNavController. This will do the following:

5. Implement setupActionBarWithNavController

MainActivity.kt

private fun setupActionBar(navController: NavController,
                           appBarConfig : AppBarConfiguration) {
    setupActionBarWithNavController(navController, appBarConfig)
}

You should also have NavigationUI handle what happens when the Up button is pressed.

6. Override onSupportNavigationUp and call NavigationUI.navigateUp, using the same AppBarConfiguration.

MainActivity.kt

override fun onSupportNavigateUp(): Boolean {
    return findNavController(R.id.my_nav_host_fragment).navigateUp(appBarConfiguration)
}

7. Run your code. If you open the app in split screen, you should have a working navigation drawer. The up icon and the drawer icon should display at the appropriate times and work correctly.

Adding new destinations to a NavigationView is easy. Once you have the navigation drawer working with up and back navigation, you just need to add the new menu item.

8. Open menu/nav_drawer_menu.xml

9. Add a new menu item for settings_dest

nav_drawer_menu.xml

<item
    android:id="@+id/settings_dest"
    android:icon="@drawable/ic_settings"
    android:title="@string/settings" />

Now your navigation drawers shows the Settings screen as a destination. Good work!

Deep Links and Navigation

Navigation components also include deep link support. Deep links are a way to jump into the middle of your app's navigation, whether that's from an actual URL link or a pending intent from a notification.

One benefit of using the navigation library to handle deep links is that it ensures users start on the right destination with the appropriate back stack from other entry points such as app widgets, notifications, or web links (covered in the next step).

Navigation provides a NavDeepLinkBuilder class to construct a PendingIntent that will take the user to a specific destination.

Add a Deep Link

We'll use the NavDeepLinkBuilder to hook up an app widget to a destination.

1. Open DeepLinkAppWidgetProvider.kt

2. Add a PendingIntent constructed with NavDeepLinkBuilder:

DeepLinkAppWidgetProvider

val args = Bundle()
args.putString("myarg", "From Widget");
val pendingIntent = NavDeepLinkBuilder(context)
        .setGraph(R.navigation.mobile_navigation)
        .setDestination(R.id.deeplink_dest)
        .setArguments(args)
        .createPendingIntent()

remoteViews.setOnClickPendingIntent(R.id.deep_link_button, pendingIntent)

Notice:

3. Add the Deep Link widget to your home screen. Tap and hold on the home screen to see option to add widget.

Tap and hold

Scroll down to find widget

When you're finished, you'll have a deep link widget.

4. Tap the widget, and verify that the Android destination opens with the correct argument. It should say "From Widget" at the top since that is the argument you passed in DeepLinkAppWidgetProvider.

5. Verify that hitting the back button takes you to the home_dest destination.

DeepLink Backstack

The backstack for a deep link is determined using the navigation graph you pass in. If the explicit Activity you've chosen has a parent activity, those parent Activities are also included.

The backstack is generated using the destinations specified with app:startDestination. In this app we only have one activity and one level of navigation, so the backstack will take you to the home_dest destination.

More complicated navigation can include nested navigation graphs. The app:startDestination at each level of the nested graphs determines the backstack. For more information on deep links and nested graphs, check out the Principles of Navigation.

The <deepLink> element

One of the most common uses of a deep link is to allow a web link to open an activity in your app. Traditionally you would use an intent-filter and associate a URL with the activity you want to open.

The navigation library makes this extremely simple and allows you to map URLs directly to destinations in your navigation graph.

<deepLink> is an element you can add to a destination in your graph. Each <deepLink> element has a single required attribute: app:uri.

In addition to a direct URI match, the following features are supported:

Add a URIbased Deep Link using <deepLink>

In this step, you'll add a deep link to www.example.com.

1. Open mobile_navigation.xml

2. Add a <deepLink> element to the deeplink_dest destination.

mobile_navigation.xml

<fragment
    android:id="@+id/deeplink_dest"
    android:name="com.example.android.codelabs.navigation.DeepLinkFragment"
    android:label="@string/deeplink"
    tools:layout="@layout/deeplink_fragment">

    <argument
        android:name="myarg"
        android:defaultValue="Android!"/>

    <deepLink app:uri="www.example.com/{myarg}" />
</fragment>

3. Open AndroidManifest.xml

4. Add the nav-graph tag. This will ensure the appropriate intent filter is generated

AndroidManifest.xml

<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <nav-graph android:value="@navigation/mobile_navigation" />
</activity>

5. Launch your app using a deep link. There are two ways to do this:

adb shell am start -a android.intent.action.VIEW -d "http://www.example.com/urlTest" 

Opened using the search bar

(not in Chrome)

Disambiguation dialog

Either way, you should see the message "urlTest" on screen. This was passed through to the fragment, from the URL.

There's one more part of the codelab app for you to experiment with, and that's the shopping cart button.

This is a recap of the skills you've learned during this codelab. This step does not include comments, so try it on your own:

  1. Create a new fragment class
  2. Add the fragment as a destination to your navigation graph
  3. Have the shopping cart icon open up your new fragment class, using NavigationUI to handle the menu.

You're familiar with the basic concepts behind the Navigation component! In this codelab you learned about:


You can continue to explore with this app or start using navigation in your own app.

There's a lot more to try, including:

For more about the Navigation Component check out the documentation. If you're interested in learning about other Architecture Components, try the following codelabs: