# How to navigate using Jetpack Compose Navigation with examples

> A Jetpack Compose tutorial that introduces the basics of Navigation. Includes code samples and Github Repo.

Published 21 July 2022 by Alex Styl.

This tutorial will cover how to implement Navigation in your Jetpack Compose application using the [AndroidX Compose Navigation](https://developer.android.com/jetpack/compose/navigation) library.

## Required dependency

Include the required dependency in your project's `build.gradle` file:

```gradle
dependencies {
    def nav_version = "2.5.0"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}
```

## How to navigate between screens

Create a `NavHost()` and pass a `NavController` and the _start_ route.

The `NavController` is used to perform navigation operations (such as navigate to the next screen or go back). Within the lambda function pass the available destinations (screens) of your app.

A basic app with a home screen and an about screen would look like this:

```kotlin
val navController = rememberNavController()
NavHost(navController, startDestination = "home") {
    composable("home") {
        HomeScreen(onAboutClick = {
            navController.navigate("about")
        })
    }
    composable("about") {
        AboutScreen()
    }
}
```

## How to pass data across destinations

When defining the route of your destination, pass in the argument(s) required as part of the route. The arguments need to be defined in a url like fashion:

`route/{argument1}/{argument2}`

named arguments are also supported:

`route/argument1={argument1}/argument2={argument2}`

pass the `arguments` as parameters in your destination. Each `navArgument()` requires a _name_ and the expected type.

An example of a details screen requiring an id would look like this:

```kotlin
composable("details/{id}",
    arguments = listOf(navArgument("id") {
        type = NavType.LongType
    })) {
    val id = requireNotNull(it.arguments).getLong("id")
    DetailsScreen(id)
}
```

navigate to the destination using the `NavController`:

```kotlin
val id = 1000L
navController.navigate("details/id=$id")
```

## How to pass optional data across destinations

Any optional data needs to be defined as a query parameter. Include them in your route appending your required arguments with a `?`:

`route/{requiredArg1}?{optional}`

additionally, mark the `navArgument()` as `nullable`:

```kotlin
composable(
    "details/{id}?{name}",
    arguments = listOf(
        navArgument("id") {
            type = NavType.LongType
        },
        navArgument("name") {
            type = NavType.StringType
            nullable = true
        }
    ),
) { backStackEntry ->
    val arguments = requireNotNull(backStackEntry.arguments)
    val id = arguments.getLong("id")
    val name = arguments.getString("name")
    DetailsScreen(id, name)
}
```

navigate to the destination using the `NavController`:

```kotlin
val id = 1000L
val name = "Alex"
navController.navigate("details/id=$id?name=$name")
```

## How to navigate to the previous screen

Use the `navController.popBackStack()` to remove the current destination from the back stack. This will cause the app to navigate to the previous destination, if there is one.

Keep in mind that the Navigation library follows the [Principles of Navigation](https://developer.android.com/guide/navigation/navigation-principles) and will _never_ terminate your application. If you wish to finish your activity if you are in the top-level destination of your app, use the return value of `popBackStack()` and call `finish()` if the value is true.

```kotlin
if(navController.popBackStack().not()) {
    finish()
}
```

## Checkout the Sample on Github

Check out the repository on Github and try it out on your machine: https://github.com/alexstyl/navigation-tutorial

---

## Related Resources

- [Principles of Navigation](https://developer.android.com/guide/navigation/navigation-principles): The Navigation library expects you to follow the Principles of Navigation while implementing. It is worth being aware of them so that you can understand its behavior and how to structure you graphs.
- [Compose Destinations](https://github.com/raamcosta/compose-destinations): A library made by [Rafael Costa](https://twitter.com/raamcosta) that dramatically removes the boilerplate required for navigation.