Navigation bar

The navigation bar allows users to switch between destinations in an app. You should use navigation bars for:

Three to five destinations of equal importance
Compact window sizes
Consistent destinations across app screens

Figure 1. A navigation bar with 4 destinations.

This page shows you how to display a navigation bar in your app with related screens and basic navigation.

API surface

Use the NavigationBar and NavigationBarItem composables to implement destination switching logic. Each NavigationBarItem represents a singular destination.

NavigationBarItem includes the following key parameters:

selected: Determines whether the current item is visually highlighted.
onClick(): Defines the action to be performed when the user clicks on the item. Logic for handling navigation events, updating the selected item state, or loading corresponding content belongs here.
label: Displays text within the item. Optional.
icon: Displays an icon within the item. Optional.

Example: Bottom navigation bar

The following snippet implements a bottom navigation bar with items so users can navigate between different screens in an app:

@Composable
funNavigationBarExample(modifier:Modifier=Modifier){
valnavController=rememberNavController()
valstartDestination=Destination.SONGS
varselectedDestinationbyrememberSaveable{mutableIntStateOf(startDestination.ordinal)}
Scaffold(
modifier=modifier,
bottomBar={
NavigationBar(windowInsets=NavigationBarDefaults.windowInsets){
Destination.entries.forEachIndexed{index,destination->
NavigationBarItem(
selected=selectedDestination==index,
onClick={
navController.navigate(route=destination.route)
selectedDestination=index
},
icon={
Icon(
destination.icon,
contentDescription=destination.contentDescription
)
},
label={Text(destination.label)}
)
}
}
}
){contentPadding->
AppNavHost(navController,startDestination,modifier=Modifier.padding(contentPadding))
}
}Navigation.kt

Key points

NavigationBar displays a collection of items, with each item corresponding to a Destination.
val navController = rememberNavController() creates and remembers an instance of NavHostController, which manages the navigation within a NavHost.
var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } manages the state of the selected item.
- startDestination.ordinal gets the numerical index (position) of the Destination.SONGS enum entry.
When an item is clicked, navController.navigate(route = destination.route) is called to navigate to the corresponding screen.
The onClick lambda of the NavigationBarItem updates the selectedDestination state to visually highlight the clicked item.
The navigation logic calls the AppNavHost composable, passing the navController and startDestination, to display the actual content of the selected screen.

Result

The following image shows the navigation bar resulting from the previous snippet:

Figure 2. A navigation bar that contains 3 destinations with associated icons: Songs, Album, and Playlist.