The Navigation Architecture Component Tutorial: Getting Started
- Why Do You Need Yet Another Component?
- Getting Started
- Adding the Navigation Architecture Component
- Navigation Graph
- Declaring a Start Destination
- NavHost Interface
- Connecting Destinations
- Navigation Editor
- Navigating From a Menu
- Passing Data and Animating Actions
- Passing Data Between Destinations
- Adding Transitions
- Types of Destinations
- Adding New Destination Types
- Common Destinations
- Deep Links
- Nested graphs
- Conditional Navigation
- Where to Go From Here?
Among other goodies, Android Jetpack comes with the Navigation architecture component, which simplifies the implementation of navigation in Android apps.
In this tutorial, you’ll add navigation to a simple book-searching app and learn about:
- Navigation graphs and nested graphs.
- Actions and destinations.
- How to pass data between destinations.
- Creating deep links.
The Navigation architecture component is still in early development, but it is already proving to be a powerful and handy tool, as you will see for yourself.
Why Do You Need Yet Another Component?
Navigating between screens — passing data, handling the back stack, implementing deep links, etc. — can be complicated. It also comes with quite a bit of boilerplate. To top it off, you should adhere to the new principles of navigation:
- The app should have a fixed start destination.
- A stack is used to represent the navigation state of an app.
- The Up button never exits your app.
- Up and Back are equivalent within your app’s task.
- Deep linking to a destination or navigating to the same destination should yield the same stack.
By using the Navigation architecture component, you provide a consistent and predictable experience to users — hassle and boilerplate free.
To use the Navigation architecture component, you must use Android Studio 3.2 or higher. Install it by following the instructions in our Beginning Android development tutorial. Make sure to install the latest stable release.
Next, download the materials for this tutorial using the Download materials button at the top or bottom of the tutorial.
Open Android Studio and import the starter project with File ▸ Open. Find the location where you extracted the starter project, highlight the root folder of the starter project, and click Open. The sample project is named Bookmans Treasure. Once the project is synced, build and run it.
If you see a blank screen, you’re on the right track.
Adding the Navigation Architecture Component
Open the build.gradle file in the app folder and add the following to the
implementation "android.arch.navigation:navigation-fragment-ktx:1.0.0-alpha05" implementation "android.arch.navigation:navigation-ui-ktx:1.0.0-alpha05"
Wondering about the -ktx suffix in the library names? It signifies the Android KTX libraries that are super nice to use with Kotlin by making your code both more concise and readable.
Sync the project. Then build and run the app again.
It’s still blank, but hold tight — you are now ready to start working on the screen navigation.
A set of destinations and actions compose an app’s navigation graph:
The above represents the navigation graph for the Bookmans Treasure app. Nodes represent the screens and arrows show how you navigate between them.
You’ll add the navigation graph to the app now.
You must first enable the Navigation Editor. Click File ▸ Settings (or Android Studio ▸ Preferences on Mac), choose the Experimental category in the left panel, check Enable Navigation Editor:
Click OK and then restart Android Studio.
Now be sure Android is selected in the Project navigator.
Click on the res folder, press command+N (on Mac) or Alt+N (on PC) (or File ▸ New) and select Android Resource File.
A dialog to create a new resource will pop up. Under File name, enter nav_graph. Under Resource type, select Navigation:
Android Studio will create a new resource directory called navigation with a new file named nav_graph.xml. This is where your navigation graph will live.
Opening nav_graph.xml, you can toggle between the Text editor and the Navigation editor by clicking the tabs at the bottom of the editor window.
Click on the Text tab to open the XML editor.
Each destination represents a screen you can navigate to. By default, the Navigation architecture component includes support for Activities and Fragments. You’ll learn how to add custom types later in this tutorial.
Add the following between the
<fragment android:id="@+id/bookSearchFragment" android:name="com.raywenderlich.android.bookmanstreasure.ui.booksearch.BookSearchFragment" android:label="Book Search Fragment" tools:layout="@layout/fragment_book_search"> </fragment>
You might get an error on the
tools:layout attribute. To fix it, add
tools namespace declaration to the navigation tag:
You can do this manually or place your cursor on
tools:layout and press Alt+Enter (on PC) or command+return(on Mac). You’ll get a Quick action pop-up:
Choose Create namespace declaration.
BookSearchFragment a destination.
Fragment destinations have the following attributes:
android:id: A unique resource name for this destination.
android:name: A fully qualified class name.
Fragmentlayout, rendered by the Navigation editor.
Build and run the app. Getting fed up with the blank screen yet?
Declaring a Start Destination
Every app needs a starting point. To declare a starting destination in the navigation graph, add the following attribute to the
app namespace yields an error, follow the same set of steps you used above for the
tools namespace to fix it. Build and run to make sure there are no errors. Seriously — blank screen, again?
You’re missing one more thing: the
NavHost interface enables destinations to be swapped in and out. The Navigation architecture component provides a default implementation: the
Open activity_main.xml layout file located in res/layout. Look for the
FrameLayout with ID
placeholder and replace it with the following fragment:
<fragment android:id="@+id/navHostFragment" android:name="androidx.navigation.fragment.NavHostFragment" android:layout_width="match_parent" android:layout_height="match_parent" app:navGraph="@navigation/nav_graph" app:defaultNavHost="true" />
Note the two new attributes:
app:navGraph: Specifies which navigation graph will be associated with the navigation host.
app:defaultNavHost: If set to
true, the navigation host will intercept the Back button.
To ensure the Back button works properly, you also need to override the
onSupportNavigateUp() method in
MainActivity.kt. Paste this chunk of code anywhere in the class:
override fun onSupportNavigateUp() = findNavController(this, R.id.navHostFragment).navigateUp()
And add the import statement, if necessary:
Now, build and run the project. No more blank screens!