androidx.wear.compose.navigation

Classes

SwipeDismissableNavHostState	State for SwipeDismissableNavHost
WearNavigator	Navigator that navigates through Composables.
WearNavigator.Destination	NavDestination specific to WearNavigator

Top-level functions summary

Unit	@Composable SwipeDismissableNavHost(     navController: NavHostController,     graph: NavGraph,     modifier: Modifier,     userSwipeEnabled: Boolean,     state: SwipeDismissableNavHostState ) Provides a place in the Compose hierarchy for self-contained navigation to occur, with backwards navigation provided by a swipe gesture.
Unit	@Composable SwipeDismissableNavHost(     navController: NavHostController,     startDestination: String,     modifier: Modifier,     userSwipeEnabled: Boolean,     state: SwipeDismissableNavHostState,     route: String?,     builder: NavGraphBuilder.() -> Unit ) Provides a place in the Compose hierarchy for self-contained navigation to occur, with backwards navigation provided by a swipe gesture.
NavHostController	@Composable rememberSwipeDismissableNavController() Creates a NavHostController that handles the adding of the WearNavigator from androidx.wear.compose.navigation.
SwipeDismissableNavHostState	@Composable rememberSwipeDismissableNavHostState(     swipeToDismissBoxState: SwipeToDismissBoxState ) Create a SwipeToDismissBoxState and remember it.

Extension functions summary

Unit	NavGraphBuilder.composable(     route: String,     arguments: List<NamedNavArgument>,     deepLinks: List<NavDeepLink>,     content: @Composable (NavBackStackEntry) -> Unit ) Utility function for building Wear Compose navigation graphs.
State<NavBackStackEntry?>	@Composable NavController.currentBackStackEntryAsState() Gets the current navigation back stack entry as a State.

Top-level functions

SwipeDismissableNavHost

Artifact: androidx.wear.compose:compose-navigation

View Source

Added in 1.4.0

@Composable
fun SwipeDismissableNavHost(
    navController: NavHostController,
    graph: NavGraph,
    modifier: Modifier = Modifier,
    userSwipeEnabled: Boolean = true,
    state: SwipeDismissableNavHostState = rememberSwipeDismissableNavHostState()
): Unit

Provides a place in the Compose hierarchy for self-contained navigation to occur, with backwards navigation provided by a swipe gesture.

Once this is called, any Composable within the given NavGraphBuilder can be navigated to from the provided navController.

The builder passed into this method is remembered. This means that for this NavHost, the contents of the builder cannot be changed.

Content is displayed within a BasicSwipeToDismissBox, showing the current navigation level. During a swipe-to-dismiss gesture, the previous navigation level (if any) is shown in the background. BackgroundScrimColor and ContentScrimColor of it are taken from LocalSwipeToDismissBackgroundScrimColor and LocalSwipeToDismissContentScrimColor.

Example of a SwipeDismissableNavHost alternating between 2 screens:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.wear.compose.material.Button
import androidx.wear.compose.material.Text
import androidx.wear.compose.navigation.SwipeDismissableNavHost
import androidx.wear.compose.navigation.composable
import androidx.wear.compose.navigation.rememberSwipeDismissableNavController

// Example of using a NavHost where each destination in the NavGraph has a unique name.
val navController = rememberSwipeDismissableNavController()
SwipeDismissableNavHost(navController = navController, startDestination = "off") {
    composable("off") {
        Column(
            modifier = Modifier.fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Button(onClick = { navController.navigate("on") }) { Text("On") }
        }
    }
    composable("on") {
        Column(
            modifier = Modifier.fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Button(onClick = { navController.navigate("off") }) { Text("Off") }
        }
    }
}

Example of a SwipeDismissableNavHost for which a destination has a named argument:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import androidx.navigation.NavType
import androidx.navigation.navArgument
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.material.CompactChip
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text
import androidx.wear.compose.navigation.SwipeDismissableNavHost
import androidx.wear.compose.navigation.composable
import androidx.wear.compose.navigation.rememberSwipeDismissableNavController

// Example of using a NavHost where we pass an argument to a destination in the NavGraph.
val navController = rememberSwipeDismissableNavController()
SwipeDismissableNavHost(navController = navController, startDestination = "list") {
    composable("list") {
        ScalingLazyColumn(
            modifier = Modifier.fillMaxSize(),
            contentPadding = PaddingValues(horizontal = 8.dp, vertical = 32.dp),
            verticalArrangement = Arrangement.Center,
        ) {
            item { ListHeader { Text("List Screen") } }
            items(5) { index ->
                CompactChip(
                    modifier = Modifier.padding(vertical = 4.dp),
                    onClick = { navController.navigate("detail/$index") },
                    label = {
                        Text(
                            text = "Item $index",
                            textAlign = TextAlign.Center,
                            modifier = Modifier.fillMaxSize()
                        )
                    }
                )
            }
        }
    }
    composable(
        route = "detail/{Id}",
        arguments = listOf(navArgument("Id") { type = NavType.IntType })
    ) { backStackEntry ->
        val itemId = backStackEntry.arguments?.getInt("Id") ?: 0
        Column(
            modifier = Modifier.fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            ListHeader { Text("Details Screen") }
            Text("Item $itemId")
        }
    }
}

Parameters
navController: NavHostController	NavHostController for this host
graph: NavGraph	Graph for this host
modifier: Modifier = Modifier	Modifier to be applied to the layout
userSwipeEnabled: Boolean = true	Boolean Whether swipe-to-dismiss gesture is enabled.
state: SwipeDismissableNavHostState = rememberSwipeDismissableNavHostState()	State containing information about ongoing swipe and animation.

Throws
kotlin.IllegalArgumentException	if no WearNavigation.Destination is on the navigation backstack.

SwipeDismissableNavHost

Artifact: androidx.wear.compose:compose-navigation

View Source

Added in 1.4.0

@Composable
fun SwipeDismissableNavHost(
    navController: NavHostController,
    startDestination: String,
    modifier: Modifier = Modifier,
    userSwipeEnabled: Boolean = true,
    state: SwipeDismissableNavHostState = rememberSwipeDismissableNavHostState(),
    route: String? = null,
    builder: NavGraphBuilder.() -> Unit
): Unit

Provides a place in the Compose hierarchy for self-contained navigation to occur, with backwards navigation provided by a swipe gesture.

Once this is called, any Composable within the given NavGraphBuilder can be navigated to from the provided navController.

The builder passed into this method is remembered. This means that for this NavHost, the contents of the builder cannot be changed.

Content is displayed within a BasicSwipeToDismissBox, showing the current navigation level. During a swipe-to-dismiss gesture, the previous navigation level (if any) is shown in the background. BackgroundScrimColor and ContentScrimColor of it are taken from LocalSwipeToDismissBackgroundScrimColor and LocalSwipeToDismissContentScrimColor.

Example of a SwipeDismissableNavHost alternating between 2 screens:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.wear.compose.material.Button
import androidx.wear.compose.material.Text
import androidx.wear.compose.navigation.SwipeDismissableNavHost
import androidx.wear.compose.navigation.composable
import androidx.wear.compose.navigation.rememberSwipeDismissableNavController

// Example of using a NavHost where each destination in the NavGraph has a unique name.
val navController = rememberSwipeDismissableNavController()
SwipeDismissableNavHost(navController = navController, startDestination = "off") {
    composable("off") {
        Column(
            modifier = Modifier.fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Button(onClick = { navController.navigate("on") }) { Text("On") }
        }
    }
    composable("on") {
        Column(
            modifier = Modifier.fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Button(onClick = { navController.navigate("off") }) { Text("Off") }
        }
    }
}

Example of a SwipeDismissableNavHost for which a destination has a named argument:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import androidx.navigation.NavType
import androidx.navigation.navArgument
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.material.CompactChip
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text
import androidx.wear.compose.navigation.SwipeDismissableNavHost
import androidx.wear.compose.navigation.composable
import androidx.wear.compose.navigation.rememberSwipeDismissableNavController

// Example of using a NavHost where we pass an argument to a destination in the NavGraph.
val navController = rememberSwipeDismissableNavController()
SwipeDismissableNavHost(navController = navController, startDestination = "list") {
    composable("list") {
        ScalingLazyColumn(
            modifier = Modifier.fillMaxSize(),
            contentPadding = PaddingValues(horizontal = 8.dp, vertical = 32.dp),
            verticalArrangement = Arrangement.Center,
        ) {
            item { ListHeader { Text("List Screen") } }
            items(5) { index ->
                CompactChip(
                    modifier = Modifier.padding(vertical = 4.dp),
                    onClick = { navController.navigate("detail/$index") },
                    label = {
                        Text(
                            text = "Item $index",
                            textAlign = TextAlign.Center,
                            modifier = Modifier.fillMaxSize()
                        )
                    }
                )
            }
        }
    }
    composable(
        route = "detail/{Id}",
        arguments = listOf(navArgument("Id") { type = NavType.IntType })
    ) { backStackEntry ->
        val itemId = backStackEntry.arguments?.getInt("Id") ?: 0
        Column(
            modifier = Modifier.fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            ListHeader { Text("Details Screen") }
            Text("Item $itemId")
        }
    }
}

Parameters
navController: NavHostController	The navController for this host
startDestination: String	The route for the start destination
modifier: Modifier = Modifier	The modifier to be applied to the layout
userSwipeEnabled: Boolean = true	Boolean Whether swipe-to-dismiss gesture is enabled.
state: SwipeDismissableNavHostState = rememberSwipeDismissableNavHostState()	State containing information about ongoing swipe and animation.
route: String? = null	The route for the graph
builder: NavGraphBuilder.() -> Unit	The builder used to construct the graph

rememberSwipeDismissableNavController

Artifact: androidx.wear.compose:compose-navigation

View Source

Added in 1.0.0

@Composable
fun rememberSwipeDismissableNavController(): NavHostController

Creates a NavHostController that handles the adding of the WearNavigator from androidx.wear.compose.navigation.

rememberSwipeDismissableNavHostState

Artifact: androidx.wear.compose:compose-navigation

View Source

Added in 1.4.0

@Composable
fun rememberSwipeDismissableNavHostState(
    swipeToDismissBoxState: SwipeToDismissBoxState = rememberSwipeToDismissBoxState()
): SwipeDismissableNavHostState

Create a SwipeToDismissBoxState and remember it.

Parameters
swipeToDismissBoxState: SwipeToDismissBoxState = rememberSwipeToDismissBoxState()	State for BasicSwipeToDismissBox, which is used to support the swipe-to-dismiss gesture in SwipeDismissableNavHost and can also be used to support edge-swiping, using edgeSwipeToDismiss.

Extension functions

composable

Artifact: androidx.wear.compose:compose-navigation

View Source

Added in 1.0.0

fun NavGraphBuilder.composable(
    route: String,
    arguments: List<NamedNavArgument> = emptyList(),
    deepLinks: List<NavDeepLink> = emptyList(),
    content: @Composable (NavBackStackEntry) -> Unit
): Unit

Utility function for building Wear Compose navigation graphs.

Adds the content composable to the NavGraphBuilder as a WearNavigator.Destination.

Parameters
route: String	route for the destination
arguments: List<NamedNavArgument> = emptyList()	list of arguments to associate with destination
deepLinks: List<NavDeepLink> = emptyList()	list of deep links to associate with the destinations
content: @Composable (NavBackStackEntry) -> Unit	composable for the destination

currentBackStackEntryAsState

Artifact: androidx.wear.compose:compose-navigation

View Source

Added in 1.0.0

@Composable
fun NavController.currentBackStackEntryAsState(): State<NavBackStackEntry?>

Gets the current navigation back stack entry as a State. When the given navController changes the back stack due to a NavController.navigate or NavController.popBackStack this will trigger a recompose and return the top entry on the back stack.

Returns
State<NavBackStackEntry?>	state of the current back stack entry