androidx.navigation.ui

Interfaces

AppBarConfiguration.OnNavigateUpListener

Interface for providing custom 'up' behavior beyond what is provided by androidx.navigation.NavController.navigateUp.

Classes

AppBarConfiguration

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.
AppBarConfiguration.Builder

The Builder class for constructing new AppBarConfiguration instances.

Objects

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.

Annotations

NavigationUiSaveStateControl

Top-level functions summary

inline AppBarConfiguration
AppBarConfiguration(
    navGraph: NavGraph,
    drawerLayout: Openable?,
    noinline fallbackOnNavigateUpListener: () -> Boolean
)

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.
inline AppBarConfiguration
AppBarConfiguration(
    topLevelDestinationIds: Set<Int>,
    drawerLayout: Openable?,
    noinline fallbackOnNavigateUpListener: () -> Boolean
)

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.
inline AppBarConfiguration
AppBarConfiguration(
    topLevelMenu: Menu,
    drawerLayout: Openable?,
    noinline fallbackOnNavigateUpListener: () -> Boolean
)

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.

Extension functions summary

Boolean

Handles the Up button by delegating its behavior to the given NavController.
Boolean

Handles the Up button by delegating its behavior to the given NavController.
Boolean

Attempt to navigate to the NavDestination associated with this MenuItem.
Unit

Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar for use with a NavController.
Unit
AppCompatActivity.setupActionBarWithNavController(
    navController: NavController,
    drawerLayout: DrawerLayout?
)

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

Sets up a NavigationBarView for use with a NavController.
Unit

Sets up a NavigationView for use with a NavController.
Unit
Toolbar.setupWithNavController(
    navController: NavController,
    configuration: AppBarConfiguration
)

Sets up a Toolbar for use with a NavController.
Unit
Toolbar.setupWithNavController(
    navController: NavController,
    drawerLayout: DrawerLayout?
)

Sets up a Toolbar for use with a NavController.
Unit
CollapsingToolbarLayout.setupWithNavController(
    toolbar: Toolbar,
    navController: NavController,
    configuration: AppBarConfiguration
)

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.
Unit
CollapsingToolbarLayout.setupWithNavController(
    toolbar: Toolbar,
    navController: NavController,
    drawerLayout: DrawerLayout?
)

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

Top-level functions

AppBarConfiguration

inline fun AppBarConfiguration(
    navGraph: NavGraph,
    drawerLayout: Openable? = null,
    noinline fallbackOnNavigateUpListener: () -> Boolean = { false }
): AppBarConfiguration

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.

Parameters
navGraph: NavGraph

The NavGraph whose start destination should be considered the only top level destination. The Up button will not be displayed when on the start destination of the graph.
drawerLayout: Openable? = null

The Openable layout that should be toggled from the Navigation button. The the Navigation button will show a drawer symbol when it is not being shown as an Up button.
noinline fallbackOnNavigateUpListener: () -> Boolean = { false }

Lambda that will be invoked if androidx.navigation.NavController.navigateUp returns false

AppBarConfiguration

inline fun AppBarConfiguration(
    topLevelDestinationIds: Set<Int>,
    drawerLayout: Openable? = null,
    noinline fallbackOnNavigateUpListener: () -> Boolean = { false }
): AppBarConfiguration

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.

Parameters
topLevelDestinationIds: Set<Int>

The set of destinations by id considered at the top level of your information hierarchy. The Up button will not be displayed when on these destinations.
drawerLayout: Openable? = null

The Openable layout that should be toggled from the Navigation button. The the Navigation button will show a drawer symbol when it is not being shown as an Up button.
noinline fallbackOnNavigateUpListener: () -> Boolean = { false }

Lambda that will be invoked if androidx.navigation.NavController.navigateUp returns false

AppBarConfiguration

inline fun AppBarConfiguration(
    topLevelMenu: Menu,
    drawerLayout: Openable? = null,
    noinline fallbackOnNavigateUpListener: () -> Boolean = { false }
): AppBarConfiguration

Configuration options for NavigationUI methods that interact with implementations of the app bar pattern such as androidx.appcompat.widget.Toolbar, com.google.android.material.appbar.CollapsingToolbarLayout, and androidx.appcompat.app.ActionBar.

Parameters
topLevelMenu: Menu

A Menu containing MenuItems corresponding with the destinations considered at the top level of your information hierarchy. The Up button will not be displayed when on these destinations.
drawerLayout: Openable? = null

The Openable layout that should be toggled from the Navigation button. The the Navigation button will show a drawer symbol when it is not being shown as an Up button.
noinline fallbackOnNavigateUpListener: () -> Boolean = { false }

Lambda that will be invoked if androidx.navigation.NavController.navigateUp returns false

Extension functions

navigateUp

fun NavController.navigateUp(appBarConfiguration: AppBarConfiguration): Boolean

Handles the Up button by delegating its behavior to the given NavController.

Returns
Boolean

True if the NavController was able to navigate up.

navigateUp

fun NavController.navigateUp(drawerLayout: Openable?): Boolean

Handles the Up button by delegating its behavior to the given NavController.

This is equivalent to calling NavController.navigateUp if the Openable layout is null.

Returns
Boolean

True if the NavController was able to navigate up.

onNavDestinationSelected

fun MenuItem.onNavDestinationSelected(navController: NavController): Boolean

Attempt to navigate to the NavDestination associated with this MenuItem.

Importantly, it assumes the getItemId matches a valid action id or destination 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.

Returns
Boolean

True if the NavController was able to navigate to the destination.

setupActionBarWithNavController

fun AppCompatActivity.setupActionBarWithNavController(
    navController: NavController,
    configuration: AppBarConfiguration = AppBarConfiguration(navController.graph)
): 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 label).

The AppBarConfiguration you provide controls how the Navigation button is displayed.

You are responsible for calling NavController.navigateUp to handle the Navigation button. Typically this is done in AppCompatActivity.onSupportNavigateUp.

Parameters
navController: NavController

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

Additional configuration options for customizing the behavior of the ActionBar

setupActionBarWithNavController

fun AppCompatActivity.setupActionBarWithNavController(
    navController: NavController,
    drawerLayout: DrawerLayout?
): 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 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 drawerLayout is non null. On all other destinations, the ActionBar will show the Up button.

You are responsible for calling NavController.navigateUp to handle the Navigation button. Typically this is done in AppCompatActivity.onSupportNavigateUp.

Parameters
navController: NavController

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

The DrawerLayout that should be toggled from the Navigation button

setupWithNavController

fun NavigationBarView.setupWithNavController(navController: NavController): Unit

Sets up a NavigationBarView for use with a NavController. This will call android.view.MenuItem.onNavDestinationSelected when a menu item is selected.

The selected item in the NavigationView will automatically be updated when the destination changes.

setupWithNavController

fun NavigationView.setupWithNavController(navController: NavController): Unit

Sets up a NavigationView for use with a NavController. This will call android.view.MenuItem.onNavDestinationSelected when a menu item is selected.

The selected item in the NavigationView will automatically be updated when the destination changes.

setupWithNavController

fun Toolbar.setupWithNavController(
    navController: NavController,
    configuration: AppBarConfiguration = AppBarConfiguration(navController.graph)
): 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 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 NavController.navigateUp when the navigation icon is clicked.

Parameters
navController: NavController

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

Additional configuration options for customizing the behavior of the Toolbar

setupWithNavController

fun Toolbar.setupWithNavController(
    navController: NavController,
    drawerLayout: DrawerLayout?
): 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 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 drawerLayout is non null. On all other destinations, the Toolbar will show the Up button.

This method will call NavController.navigateUp when the navigation icon is clicked.

Parameters
navController: NavController

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

The DrawerLayout that should be toggled from the Navigation button

setupWithNavController

fun CollapsingToolbarLayout.setupWithNavController(
    toolbar: Toolbar,
    navController: NavController,
    configuration: AppBarConfiguration = AppBarConfiguration(navController.graph)
): Unit

Sets up a CollapsingToolbarLayout and 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 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 NavController.navigateUp when the navigation icon is clicked.

Parameters
toolbar: Toolbar

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

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

Additional configuration options for customizing the behavior of the Toolbar

setupWithNavController

fun CollapsingToolbarLayout.setupWithNavController(
    toolbar: Toolbar,
    navController: NavController,
    drawerLayout: DrawerLayout?
): Unit

Sets up a CollapsingToolbarLayout and 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 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 drawerLayout is non null. On all other destinations, the Toolbar will show the Up button.

This method will call NavController.navigateUp when the Navigation button is clicked.

Parameters
toolbar: Toolbar

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

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

The DrawerLayout that should be toggled from the Navigation button