NavigationUI

object NavigationUI

Class which hooks up elements typically in the 'chrome' of your application such as global navigation patterns like a navigation drawer or bottom nav bar with your NavController.

Summary

Public functions
Boolean
navigateUp(
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration
)

Handles the Up button by delegating its behavior to the given NavController.
Boolean
navigateUp(
    navController: <Error class: unknown class>,
    openableLayout: Openable?
)

Handles the Up button by delegating its behavior to the given NavController.
Boolean
onNavDestinationSelected(
    item: MenuItem,
    navController: <Error class: unknown class>
)

Attempt to navigate to the NavDestination associated with the given MenuItem.
Boolean
@NavigationUiSaveStateControl
onNavDestinationSelected(
    item: MenuItem,
    navController: <Error class: unknown class>,
    saveState: Boolean
)

Attempt to navigate to the NavDestination associated with the given MenuItem.
Unit
setupActionBarWithNavController(
    activity: AppCompatActivity,
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration
)

Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar for use with a NavController.
Unit
setupActionBarWithNavController(
    activity: AppCompatActivity,
    navController: <Error class: unknown class>,
    openableLayout: Openable?
)

Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar for use with a NavController.
Unit
setupWithNavController(
    navigationBarView: NavigationBarView,
    navController: <Error class: unknown class>
)

Sets up a NavigationBarView for use with a NavController.
Unit
setupWithNavController(
    navigationView: NavigationView,
    navController: <Error class: unknown class>
)

Sets up a NavigationView for use with a NavController.
Unit
@NavigationUiSaveStateControl
setupWithNavController(
    navigationBarView: NavigationBarView,
    navController: <Error class: unknown class>,
    saveState: Boolean
)

Sets up a NavigationBarView for use with a NavController.
Unit
@NavigationUiSaveStateControl
setupWithNavController(
    navigationView: NavigationView,
    navController: <Error class: unknown class>,
    saveState: Boolean
)

Sets up a NavigationView for use with a NavController.
Unit
setupWithNavController(
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration
)

Sets up a Toolbar for use with a NavController.
Unit
setupWithNavController(
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    openableLayout: Openable?
)

Sets up a Toolbar for use with a NavController.
Unit
setupWithNavController(
    collapsingToolbarLayout: CollapsingToolbarLayout,
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration
)

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.
Unit
setupWithNavController(
    collapsingToolbarLayout: CollapsingToolbarLayout,
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    openableLayout: Openable?
)

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.

Public functions

fun navigateUp(
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration
): Boolean

Handles the Up button by delegating its behavior to the given NavController. This is an alternative to using NavController.navigateUp directly when the given AppBarConfiguration needs to be considered when determining what should happen when the Up button is pressed.

In cases where no Up action is available, the AppBarConfiguration.fallbackOnNavigateUpListener will be called to provide additional control.

Parameters
navController: <Error class: unknown class>

The NavController that hosts your content.
configuration: AppBarConfiguration

Additional configuration options for determining what should happen when the Up button is pressed.
Returns
Boolean

True if the NavController was able to navigate up.

 
fun navigateUp(
    navController: <Error class: unknown class>,
    openableLayout: Openable?
): Boolean

Handles the Up button by delegating its behavior to the given NavController. This should generally be called from AppCompatActivity.onSupportNavigateUp.

If you do not have a Openable layout, you should call NavController.navigateUp directly.

Parameters
navController: <Error class: unknown class>

The NavController that hosts your content.
openableLayout: Openable?

The Openable layout that should be opened if you are on the topmost level of the app.
Returns
Boolean

True if the NavController was able to navigate up.

 
fun onNavDestinationSelected(
    item: MenuItem,
    navController: <Error class: unknown class>
): Boolean

Attempt to navigate to the NavDestination associated with the given MenuItem. This MenuItem should have been added via one of the helper methods in this class.

Importantly, it assumes the menu item id matches a valid NavDestination.getAction or NavDestination.id to be navigated to.

By default, the back stack will be popped back to the navigation graph's start destination. Menu items that have android:menuCategory="secondary" will not pop the back stack.

Parameters
item: MenuItem

The selected MenuItem.
navController: <Error class: unknown class>

The NavController that hosts the destination.
Returns
Boolean

True if the NavController was able to navigate to the destination associated with the given MenuItem.

 
@NavigationUiSaveStateControl
fun onNavDestinationSelected(
    item: MenuItem,
    navController: <Error class: unknown class>,
    saveState: Boolean
): Boolean

Attempt to navigate to the NavDestination associated with the given MenuItem. This MenuItem should have been added via one of the helper methods in this class.

Importantly, it assumes the menu item id matches a valid NavDestination.getAction or NavDestination.id to be navigated to.

By default, the back stack will be popped back to the navigation graph's start destination. Menu items that have android:menuCategory="secondary" will not pop the back stack.

Parameters
item: MenuItem

The selected MenuItem.
navController: <Error class: unknown class>

The NavController that hosts the destination.
saveState: Boolean

Whether the NavController should save the back stack state. This must always be false: leave this parameter off entirely to use the non-experimental version of this API, which saves the state by default.
Returns
Boolean

True if the NavController was able to navigate to the destination associated with the given MenuItem.

 
fun setupActionBarWithNavController(
    activity: AppCompatActivity,
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration = AppBarConfiguration.Builder(navController.graph).build()
): Unit

Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar for use with a NavController.

By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid NavDestination.label).

The AppBarConfiguration you provide controls how the Navigation button is displayed. Call navigateUp to handle the Up button.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
activity: AppCompatActivity

The activity hosting the action bar that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController whose navigation actions will be reflected in the title of the action bar.
configuration: AppBarConfiguration = AppBarConfiguration.Builder(navController.graph).build()

Additional configuration options for customizing the behavior of the ActionBar

 
fun setupActionBarWithNavController(
    activity: AppCompatActivity,
    navController: <Error class: unknown class>,
    openableLayout: Openable?
): Unit

Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar for use with a NavController.

By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid NavDestination.label).

The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the ActionBar will show the drawer icon if the given Openable layout is non null. On all other destinations, the ActionBar will show the Up button. Call navigateUp to handle the Up button.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
activity: AppCompatActivity

The activity hosting the action bar that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController whose navigation actions will be reflected in the title of the action bar.
openableLayout: Openable?

The Openable layout that should be toggled from the home button
See also
setupActionBarWithNavController 
fun setupWithNavController(
    navigationBarView: NavigationBarView,
    navController: <Error class: unknown class>
): Unit

Sets up a NavigationBarView for use with a NavController. This will call onNavDestinationSelected when a menu item is selected. The selected item in the NavigationBarView will automatically be updated when the destination changes.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
navigationBarView: NavigationBarView

The NavigationBarView (BottomNavigationView or NavigationRailView) that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController that supplies the primary menu. Navigation actions on this NavController will be reflected in the selected item in the NavigationBarView.

 
fun setupWithNavController(
    navigationView: NavigationView,
    navController: <Error class: unknown class>
): Unit

Sets up a NavigationView for use with a NavController. This will call onNavDestinationSelected when a menu item is selected. The selected item in the NavigationView will automatically be updated when the destination changes.

If the NavigationView is directly contained with an Openable layout, it will be closed when a menu item is selected.

Similarly, if the NavigationView has a BottomSheetBehavior associated with it (as is the case when using a com.google.android.material.bottomsheet.BottomSheetDialog), the bottom sheet will be hidden when a menu item is selected.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
navigationView: NavigationView

The NavigationView that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController that supplies the primary and secondary menu. Navigation actions on this NavController will be reflected in the selected item in the NavigationView.

 
@NavigationUiSaveStateControl
fun setupWithNavController(
    navigationBarView: NavigationBarView,
    navController: <Error class: unknown class>,
    saveState: Boolean
): Unit

Sets up a NavigationBarView for use with a NavController. This will call onNavDestinationSelected when a menu item is selected. The selected item in the NavigationBarView will automatically be updated when the destination changes.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
navigationBarView: NavigationBarView

The NavigationBarView (BottomNavigationView or NavigationRailView) that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController that supplies the primary menu.
saveState: Boolean

Whether the NavController should save the back stack state. This must always be false: leave this parameter off entirely to use the non-experimental version of this API, which saves the state by default.

Navigation actions on this NavController will be reflected in the selected item in the NavigationBarView.

 
@NavigationUiSaveStateControl
fun setupWithNavController(
    navigationView: NavigationView,
    navController: <Error class: unknown class>,
    saveState: Boolean
): Unit

Sets up a NavigationView for use with a NavController. This will call onNavDestinationSelected when a menu item is selected. The selected item in the NavigationView will automatically be updated when the destination changes.

If the NavigationView is directly contained with an Openable layout, it will be closed when a menu item is selected.

Similarly, if the NavigationView has a BottomSheetBehavior associated with it (as is the case when using a com.google.android.material.bottomsheet.BottomSheetDialog), the bottom sheet will be hidden when a menu item is selected.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
navigationView: NavigationView

The NavigationView that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController that supplies the primary and secondary menu.
saveState: Boolean

Whether the NavController should save the back stack state. This must always be false: leave this parameter off entirely to use the non-experimental version of this API, which saves the state by default.

Navigation actions on this NavController will be reflected in the selected item in the NavigationView.

 
fun setupWithNavController(
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration = AppBarConfiguration.Builder(navController.graph).build()
): Unit

Sets up a Toolbar for use with a NavController.

By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid NavDestination.label).

The AppBarConfiguration you provide controls how the Navigation button is displayed and what action is triggered when the Navigation button is tapped. This method will call navigateUp when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
toolbar: Toolbar

The Toolbar that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController whose navigation actions will be reflected in the title of the Toolbar.
configuration: AppBarConfiguration = AppBarConfiguration.Builder(navController.graph).build()

Additional configuration options for customizing the behavior of the Toolbar

 
fun setupWithNavController(
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    openableLayout: Openable?
): Unit

Sets up a Toolbar for use with a NavController.

By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid NavDestination.label).

The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the Toolbar will show the drawer icon if the given Openable layout is non null. On all other destinations, the Toolbar will show the Up button. This method will call navigateUp when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
toolbar: Toolbar

The Toolbar that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController whose navigation actions will be reflected in the title of the Toolbar.
openableLayout: Openable?

The Openable layout that should be toggled from the Navigation button
See also
setupWithNavController 
fun setupWithNavController(
    collapsingToolbarLayout: CollapsingToolbarLayout,
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    configuration: AppBarConfiguration = AppBarConfiguration.Builder(navController.graph).build()
): Unit

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.

By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid NavDestination.label).

The AppBarConfiguration you provide controls how the Navigation button is displayed and what action is triggered when the Navigation button is tapped. This method will call navigateUp when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
collapsingToolbarLayout: CollapsingToolbarLayout

The CollapsingToolbarLayout that should be kept in sync with changes to the NavController.
toolbar: Toolbar

The Toolbar that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController whose navigation actions will be reflected in the title of the Toolbar.
configuration: AppBarConfiguration = AppBarConfiguration.Builder(navController.graph).build()

Additional configuration options for customizing the behavior of the Toolbar

 
fun setupWithNavController(
    collapsingToolbarLayout: CollapsingToolbarLayout,
    toolbar: Toolbar,
    navController: <Error class: unknown class>,
    openableLayout: Openable?
): Unit

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.

By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid NavDestination.label).

The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the Toolbar will show the drawer icon if the given Openable layout is non null. On all other destinations, the Toolbar will show the Up button. This method will call navigateUp when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
collapsingToolbarLayout: CollapsingToolbarLayout

The CollapsingToolbarLayout that should be kept in sync with changes to the NavController.
toolbar: Toolbar

The Toolbar that should be kept in sync with changes to the NavController.
navController: <Error class: unknown class>

The NavController whose navigation actions will be reflected in the title of the Toolbar.
openableLayout: Openable?

The Openable layout that should be toggled from the Navigation button