4.2 Implementation of the Bottom Navigation Bar

The bottom navigation bar is one of the most common type of navigation system in Android apps. Implementing it in Jetpack Compose does require a bit of diligence though. This textbook page should help walk you through the process nicely and explain some of the code in more detail than the demo.

Much of this tutorial can also be applied for basic Compose navigation even if you aren't using a navbar, so if that is your use case, feel free to read on!

Step 0: Dependencies:

To start, you'll need to add the following in your libs.versions.toml file to specify the library versions. Under [libraries] and [plugins], add the corresponding lines:

libs.versions.toml

[libraries]
# ...
androidx-compose-navigation = { group = "androidx.navigation", name = "navigation-compose", version="2.8.0-beta06"}
kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version = "1.6.3" }

[plugins]
# ...
jetbrains-kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

Then, in build.gradle file, add the following lines:

build.gradle (Module: app)

plugins {
    // ...
    alias(libs.plugins.jetbrains.kotlin.serialization)
}

dependencies {
    // ...
    implementation(libs.androidx.compose.navigation)
    implementation(libs.kotlinx.serialization.json)
}

Step 1: Creating the Screen sealed class

When using type-safe navigation with compose, it's helpful to have one parent sealed class called Screen that we can use in our app. This way we instantly know which data classes are screens and which ones represent data within our app. Create a sealed class, and create a couple subclasses that extend it with some routes you want your app to have. It could be a good idea to putt this class in its own file.

We will annotate each of these classes with @Serializable, since we want Compose navigation to be able to pass these screen objects between activities, so we need to let the compiler know that these can be converted to strings.

We're also going to make ProfileScreen a data class, this will allow us to pass arguments to the screen. We specify a mandatory userId argument here, so whenever someone loads the ProfileScreen, they need to pass a userId. If you want to pass a custom object between screens, I recommend checking out this video (although it's rare that you would actually need to do this).

Screen.kt

@Serializable
sealed class Screen {
    @Serializable
    data object HomeScreen : Screen()

    @Serializable
    data object SettingsScreen : Screen()

    @Serializable
    data class ProfileScreen(val userId: String) : Screen()
    // ...
}

Step 2: Initializing a NavHost

The NavHost will select the correct screen to display based on the current route in its navController. It will also specify which route the app starts at. Let's initialize a navController and the corresponding NavHost . You may notice that we are using a Scaffold here. A Scaffold is a layout composable that helps us arrange a bottom bar and main content, so this is only for if you want to use bottom navigation. Also note that we wrapped our content in a Box that uses innerPadding. This is just to make sure that the content is not behind the bottomBar composable.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // ...
         
        setContent {
            FromScratchNavigationTheme {
                val navController = rememberNavController()

                Scaffold(modifier = Modifier.fillMaxSize(), bottomBar = {
                    // TODO we will create our bottom navigation bar here
                }) { innerPadding ->
                    Box(modifier = Modifier.padding(innerPadding)) {
                        NavHost(
                            navController = navController,
                            startDestination = Screen.HomeScreen
                        ) {
                            composable<Screen.HomeScreen> {
                                Text(text = "HOME: add your screen here")
                            }
                            composable<Screen.SettingsScreen> {
                                Text(text = "SETTINGS: add your screen here")
                            }
                            composable<Screen.ProfileScreen> {
                                Text(text = "PROFILE: add your screen here")
                            }
                        }
                    }
                }
            }
        }
    }
}

Step 3: Defining a bottom tab

Each app could have its own notion of a "bottom tab", depending on how you want it to look and what information you need to store. For this demo, I'm going to assume that we want each bottom tab to have an icon, label, and screen. So I am going to represent this with a data class.

data class NavItem(
    val screen: Screen,
    val label: String,
    val icon: ImageVector
)

Then, we need to specify the data of our tabs with a list. This should be held in state in the ViewModel, but for now we can just store the list of tabs in the onCreate method. Here are the tabs I made for this tutorial:

val tabs = listOf(
            NavItem(
                label = "Home",
                icon = Icons.Filled.Home,
                screen = Screen.HomeScreen,
            ),
            NavItem(
                label = "Settings",
                icon = Icons.Filled.Settings,
                screen = Screen.SettingsScreen,
            ),
            NavItem(
                label = "Profile",
                icon = Icons.Filled.Person,
                screen = Screen.ProfileScreen,
            )
        )

Step 4: Adding the navigation bar

To create the navigation bar, we're going to use the bottomBar parameter of the Scaffold layout and pass in a NavigationBar composable. We map our list of tabs to actual composable functions that display the tabs. We can use NavigationBarItem for this. The updated code now looks as follows:

Scaffold(modifier = Modifier.fillMaxSize(), bottomBar = {
            NavigationBar {
                tabs.map { item -> 
                    NavigationBarItem(
                        selected = false,  // TODO
                        onClick = { navController.navigate(item.screen) },
                        icon = { Icon(imageVector = item.icon, contentDescription = null) },
                        label = { Text(text = item.label) }
                    )
                }
            }
        }
    )

However, we still have one problem. How do we know if a NavigationBarItem is selected? For this, we want to use the navBackStackEntry. This is a variable that gives us information about the top of the navigation stack. To use this, we will want to start by creating an extension function in our Screen class that allows us to convert from a nav backstack entry to a Screen.

sealed class Screen {
    // ...
    fun NavBackStackEntry.toScreen(): Screen? =
        when (destination.route?.substringAfterLast(".")?.substringBefore("/")) {
            "HomeScreen" -> toRoute<HomeScreen>()
            "SettingsScreen" -> toRoute<SettingsScreen>()
            "ProfileScreen" -> toRoute<ProfileScreen>()
            else -> null
        }
}

Behind the scenes, a route name might look like "com.example.demo.ui.Screen.Profile/{profileId}", so to get the name of the screen, we look at the substring after the last . . Sometimes routes will have arguments passed to them, so we also have to look before the first / to find the screen name. We then use the toRoute function to automatically parse this route and convert it to its data class representation.

Then we can track the screen as follows:

val navBackStackEntry = navController.currentBackStackEntryAsState().value


Scaffold(modifier = Modifier.fillMaxSize(), bottomBar = {
    NavigationBar {
        tabs.map { item ->
            NavigationBarItem(
                selected = item.screen == navBackStackEntry?.toScreen(),
                onClick = {
                    navController.navigate(item.screen)
                },
                icon = { Icon(imageVector = item.icon, contentDescription = null) },
                label = { Text(text = item.label) }
            )
        }
    }
})

Step 5: Future Customization

Congrats, you implemented a bottom navigation bar in Jetpack Compose! Here are some tips to help you with general navigation skills:

Navigating to other screens

Let's say I wanted to navigate to a ProfileDetails screen from my Profile screen, and I wanted my Profile screen to receive an id.

It's recommended that we pass the navigation action in a lambda to ProfileScreen, instead of giving it access to the entire navController. The reason is, if we put navController as a parameter for ProfileScreen, then that makes ProfileScreen difficult to test. If we wanted to try to test ProfileScreen in isolation, we'd need to provide a mock navigator to it, instead of just being able to provide an empty lambda for navigation to other screens. Not only that, but it makes it harder to reason about the behavior of ProfileScreen , because it can use navController however it wants. So the code looks like this:

NavHost(
    // ... 
) {
    composable<Screen.Home> {
        HomeScreen(navigateToProfileDetails = { id ->
            navController.navigate(Screen.ProfileDetails(id))
        })
    }
    // ...
}

Receiving navigation arguments

To receive navigation arguments on a certain screen, we want to use the NavBackStackEntry. The composable function in NavHost actually takes a parameter of type @Composable() ((NavBackStackEntry) -> Unit), meaning that inside the composable function, the parameter we have access to is the NavBackStackEntry. This is more easily understood through example:

NavHost(
    // ... 
) {
    composable<Screen.ProfileDetails> { navBackStackEntry ->
        val profileId = navBackStackEntry.toRoute<Screen.ProfileDetails>().profileId
        ProfileDetails(profileId)
    }
    // ...
}

Whenever NavHost maps the current navigation destination to a composable, that composable provides navBackStackEntry. We can then get the arguments that we're looking for by using the toRoute function, which takes the back stack entry, and converts it to an instance of our Screen.ProfileDetails data class. We can access the fields of this data class, so that includes profileId. Then we are able to pass this as a parameter to our hypothetical ProfileDetails screen.