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

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

SwipeDismissableNavHostState

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?>

Gets the current navigation back stack entry as a State.

Top-level functions

SwipeDismissableNavHost

@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.Column
import androidx.compose.foundation.layout.fillMaxSize
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.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
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

@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.Column
import androidx.compose.foundation.layout.fillMaxSize
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.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
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

@Composable
fun rememberSwipeDismissableNavController(): NavHostController

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

rememberSwipeDismissableNavHostState

@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

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

@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