{"id":1972,"date":"2021-11-04T12:27:11","date_gmt":"2021-11-04T19:27:11","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/surface-duo\/?p=1972"},"modified":"2022-06-09T10:06:31","modified_gmt":"2022-06-09T17:06:31","slug":"jetpack-compose-navigation-rail","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/surface-duo\/jetpack-compose-navigation-rail\/","title":{"rendered":"Jetpack Compose Navigation Rail"},"content":{"rendered":"

Hello Jetpack Compose developers!<\/p>\n

This week, we released a new sample<\/a> that demonstrates how to use the NavigationRail<\/strong> component with large screen and foldable devices. These guidelines were also introduced recently in the Microsoft Surface Duo Design Kit 2.1<\/a>.<\/p>\n

Create a NavigationRail with Compose<\/h2>\n

We first blogged about NavigationRail<\/strong> in August<\/a>, when we described how to use it in a dual-screen sample with XML layouts. As a reminder, the NavigationRail<\/a> component is used for navigation on large screens and can hold 3-7 app destinations, plus a logo or floating action button.<\/p>\n

To add a NavigationRail<\/strong> to your Compose application, follow these steps:<\/p>\n

    \n
  1. Add the following dependencies to your build.gradle<\/code> file:\n
    ext {\r\n   composeVersion = \"1.1.0-alpha06\"\r\n   navVersion = \"2.4.0-alpha10\"\r\n}\r\nimplementation \"androidx.compose.material:material:$composeVersion\"\r\nimplementation \"androidx.navigation:navigation-compose:$navVersion\"<\/pre>\n
    The component is still in alpha, so make sure to update composeVersion<\/code> and navVersion<\/code> with the most recent releases, which can be found at the Compose Material<\/a> and Navigation<\/a> pages. You will also have to add the @ExperimentalMaterialApi<\/code> tag to any Composable functions that use NavigationRail<\/strong> or NavigationRailItem<\/strong>.<\/li>\n
  2. Create a composable with a NavigationRail<\/strong> that contains NavigationRailItem<\/strong> components. The code snippet below is based on an example from the NavigationRail API reference<\/a>, but similar code can be found in our sample in GalleryNavWithSelector.kt<\/a>.\n
    @ExperimentalMaterialApi\r\n@Composable\r\nfun ExampleNavRail(navController: NavHostController, items: List) {\r\n   val icons = listOf(Icons.Filled.Home, Icons.Filled.Search, Icons.Filled.Settings)\r\n\r\n   NavigationRail {\r\n       items.forEachIndexed { index, item ->\r\n           val currentDestination = navController.currentBackStackEntryAsState().value?.destination\r\n           NavigationRailItem(\r\n               icon = { Icon(icons[index], contentDescription = item) },\r\n               label = { Text(item) },\r\n               selected = currentDestination?.route?.let { it == item } ?: false,\r\n               onClick = { navController.navigate(item) }\r\n           )\r\n       }\r\n   }\r\n}<\/pre>\n<\/li>\n
  3. Add your NavigationRail<\/strong> composable next to your NavHost <\/strong>by placing them together in a Row<\/strong>.\n
    val navController = rememberNavController()\r\nval items = listOf(\"Home\", \"Search\", \"Settings\")\r\n\r\nScaffold(topBar = { TopAppBar(title = { Text(\"Example Nav Rail App\") }) }) {\r\n   Row {\r\n       ExampleNavRail(navController, items)\r\n       NavHost(navController = navController, startDestination = items.first()) {\r\n           items.forEach { item ->\r\n               composable(route = item) { Text(text = item) }\r\n           }\r\n       }\r\n   }\r\n}<\/pre>\n<\/li>\n<\/ol>\n
    Design guidelines for large screen and foldable devices UX<\/h2>\n
    When adding navigation to apps for large screen and foldable devices, we recommend using a combination of NavigationRail<\/strong> and BottomNavigation<\/strong>. In the case of Surface Duo, this means using a navigation rail when the app is spanned and switching to a bottom navigation bar when the app is unspanned.<\/p>\n
    \"Resource<\/p>\n
    Figure 1: Navigation rail guidelines from the <\/em>Surface Duo Design Kit 2.1<\/em><\/a>.<\/em><\/p>\n
    To dynamically switch between navigation components based on screen size, use a combination of the Jetpack Window Manager library<\/a> and other device properties available via LocalConfiguration.current<\/code>. On Surface Duo and other foldables, you can use Window Manager to check if a hinge is present in the form of a FoldingFeature<\/strong>, while LocalConfiguration.current<\/code> is useful for checking the size of a device\u2019s screen. To see how we used these two resources in the sample app, check out the SetupUI<\/strong> function in HomePage.kt<\/a>.<\/p>\n
    Sample highlights and challenges<\/h2>\n
    Our NavigationRail<\/strong> sample is a nature information catalog with five categories: plants, birds, animals, lakes, and rocks. Each category has multiple items, and each item has a picture and a scientific description. The app uses our custom control TwoPaneLayout<\/a> and follows the List Detail design pattern<\/a>, with the \u201clist\u201d being the gallery for the current category and the \u201cdetail\u201d being the picture and description of the selected item.<\/p>\n
    Navigation hierarchy<\/h3>\n
    In our plans for the sample, we decided on the layout designs shown in Figure 2. When it came time to implement the behavior, setting up the navigation was a bit complicated!<\/p>\n
    \"Layout\nFigure 2: Layout designs for each Surface Duo orientation.<\/em><\/p>\n
    After some thought, we realized that the BottomNavigation<\/strong>\/NavigationRail<\/strong> would always be shown in pane 1, and the associated NavHost<\/strong> would only be used to display the different galleries. Even though we would sometimes need to switch between the gallery and item views, it wouldn\u2019t make sense to add the item view to the NavHost<\/strong> as a top-level app destination.<\/p>\n
    So, the final navigation graph we settled on has two main parts. The first part, as shown in Figure 3, uses the navigation support provided by TwoPaneLayout<\/strong> to switch between the gallery and item views when only one pane is being displayed.<\/p>\n
    \"TwoPaneLayout\nFigure 3: Navigation logic within TwoPaneLayout.<\/em><\/p>\n
    The second part, seen in Figure 4, exists only within pane 1, where a NavHost<\/strong> is connected to the current navigation component to enable switching between the five different gallery categories. One important note is that because the NavHost<\/strong> only exists at the pane 1 level in the layout hierarchy, the app technically had two NavHost<\/strong> instance; one for the single pane container and another for the two pane container. To ensure that both instances were synced, we created a currentRoute<\/code> variable at the highest level of the hierarchy and checked it when recomposing pane 1.<\/p>\n
    \"NavHost\nFigure 4: Navigation logic within pane 1 with a NavHost.<\/em><\/p>\n
    Custom components<\/h3>\n
    Another challenge was creating custom components to match the designs for the sample. We found that the Jetsnack<\/a> sample from the official Compose repository was a great reference for both setting up navigation and adding custom UI components.<\/p>\n
    The first customization we made was adding a selector to the NavigationRailItem<\/strong> and BottomNavigationItem<\/strong> components. This selector appears behind the icon of the current destination and includes visibility animations (see Figure 5). If you\u2019re interested in the implementation, check out NavRailItemWithSelector.kt<\/a> and BottomNavItemWithSelector.kt<\/a>.<\/p>\n
    \"Animation<\/a>\nFigure 5: Example of how the selector highlights the current destination in the NavigationRail.<\/em><\/p>\n
    We also created a custom ContentDrawer<\/strong> component that behaves similarly to a BottomSheetScaffold<\/a>, except with an enhancement that prevents content from rendering under the hinge.<\/p>\n
    \"Animation<\/a>\nFigure 6: Demonstration of hinge aware ContentDrawer component.<\/em><\/p>\n
    This was achieved by creating a swipeable BoxWithConstraints<\/strong> and adding a Spacer<\/strong> with dynamic height based on swipe progress. The code snippet below was taken from ContentDrawer.kt<\/a>, and it shows how height was calculated using hinge properties and information from the swipeable modifier.<\/p>\n
    \/\/ Check if a spacer needs to be included to render content around an occluding hinge\r\nval spacerHeight = if (hingeOccludes) {\r\n   val isExpanding = swipeableState.progress.to == DrawerState.Expanded\r\n   val progressHeight = (hingeSize.value * swipeableState.progress.fraction).dp\r\n   if (isExpanding)\r\n       progressHeight\r\n   else\r\n       hingeSize - progressHeight\r\n} else {\r\n   0.dp\r\n}<\/pre>\n
    Resources and feedback<\/h2>\n
    For coding tips, visit the Surface Duo developer documentation<\/a> , our samples<\/a>, and Google\u2019s Android large screen development guidance<\/a>.<\/p>\n
    If you have any questions, or would like to tell us about your dual-screen apps, use the\u00a0feedback forum<\/a>\u00a0or message us on Twitter\u00a0@surfaceduodev<\/a>.<\/p>\n
    Finally, please join us for our dual screen developer livestream<\/a> at 11am (Pacific time) each Friday \u2013 mark it in your calendar and check out the archives on YouTube<\/a>.<\/p>\n
    Attribution<\/h2>\n
    The images used in the Navigation rail sample are licensed under [\u00a9 eakarat], [\u00a9 nerudol], [\u00a9 DedMityay], [\u00a9 tibor13], [\u00a9 Harry Collins], [\u00a9 Tony Baggett], [\u00a9 WildMedia], [\u00a9 Vlasto Opatovsky], [\u00a9 Lakeview Images], [\u00a9 viktoriya89], [\u00a9 dudlajzov], [\u00a9 zkbld], [\u00a9 muraviov], [\u00a9 phototrip.cz], [\u00a9 gpisano71], [\u00a9 Mike Mareen], [\u00a9 Fokke], [\u00a9 ronnybas], [\u00a9 Piotr Krzeslak], [\u00a9 shaiith], [\u00a9 aiisha], [\u00a9 Andrew Mayovskyy], [\u00a9 Andrey Armyagov], [\u00a9 \u041d\u0430\u0442\u0430\u043b\u044c\u044f \u0411\u043e\u0441\u044f\u043a] \/ stock.adobe.com<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
    Hello Jetpack Compose developers! This week, we released a new sample that demonstrates how to use the NavigationRail component with large screen and foldable devices. These guidelines were also introduced recently in the Microsoft Surface Duo Design Kit 2.1. Create a NavigationRail with Compose We first blogged about NavigationRail in August, when we described how […]<\/p>\n","protected":false},"author":72597,"featured_media":1998,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[692,473,46],"class_list":["post-1972","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-surface-duo-sdk","tag-jetpack-compose","tag-kotlin","tag-surface-duo"],"acf":[],"blog_post_summary":"
    Hello Jetpack Compose developers! This week, we released a new sample that demonstrates how to use the NavigationRail component with large screen and foldable devices. These guidelines were also introduced recently in the Microsoft Surface Duo Design Kit 2.1. Create a NavigationRail with Compose We first blogged about NavigationRail in August, when we described how […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/posts\/1972","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/users\/72597"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/comments?post=1972"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/posts\/1972\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/media\/1998"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/media?parent=1972"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/categories?post=1972"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/tags?post=1972"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}