androidx.compose.material3.adaptive.navigation3

Interfaces

ListDetailSceneScope

A scope used by a ListDetailSceneStrategy.
Cmn
SupportingPaneSceneScope

A scope used by a SupportingPaneSceneStrategy.
Cmn

Classes

ListDetailSceneStrategy

A ListDetailSceneStrategy supports arranging NavEntrys into an adaptive ListDetailPaneScaffold.
Cmn
SupportingPaneSceneStrategy

A SupportingPaneSceneStrategy supports arranging NavEntrys into an adaptive SupportingPaneScaffold.
Cmn

Top-level functions summary

ListDetailSceneStrategy<T>
@ExperimentalMaterial3AdaptiveApi
@Composable
<T : Any> rememberListDetailSceneStrategy(
    shouldHandleSinglePaneLayout: Boolean,
    backNavigationBehavior: BackNavigationBehavior,
    directive: PaneScaffoldDirective,
    adaptStrategies: ThreePaneScaffoldAdaptStrategies,
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)?,
    paneExpansionState: PaneExpansionState?
)

Creates and remembers a ListDetailSceneStrategy.
Cmn
SupportingPaneSceneStrategy<T>
@ExperimentalMaterial3AdaptiveApi
@Composable
<T : Any> rememberSupportingPaneSceneStrategy(
    shouldHandleSinglePaneLayout: Boolean,
    backNavigationBehavior: BackNavigationBehavior,
    directive: PaneScaffoldDirective,
    adaptStrategies: ThreePaneScaffoldAdaptStrategies,
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)?,
    paneExpansionState: PaneExpansionState?
)

Creates and remembers a SupportingPaneSceneStrategy.
Cmn

Top-level properties summary

ProvidableCompositionLocal<ListDetailSceneScope?>

Local provider of ListDetailSceneScope for NavEntrys which are displayed in a Material list-detail scaffold.
Cmn
ProvidableCompositionLocal<SupportingPaneSceneScope?>

Local provider of SupportingPaneSceneScope for NavEntrys which are displayed in a Material supporting pane scaffold.
Cmn

Top-level functions

rememberListDetailSceneStrategy

Cmn 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun <T : Any> rememberListDetailSceneStrategy(
    shouldHandleSinglePaneLayout: Boolean = false,
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange,
    directive: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo()),
    adaptStrategies: ThreePaneScaffoldAdaptStrategies = ListDetailPaneScaffoldDefaults.adaptStrategies(),
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null,
    paneExpansionState: PaneExpansionState? = null
): ListDetailSceneStrategy<T>

Creates and remembers a ListDetailSceneStrategy.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.material3.adaptive.navigation3.ListDetailSceneStrategy
import androidx.compose.material3.adaptive.navigation3.LocalListDetailSceneScope
import androidx.compose.material3.adaptive.navigation3.rememberListDetailSceneStrategy
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.onClick
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay

val backStack = rememberNavBackStack(HomeKey)
val sceneStrategy = rememberListDetailSceneStrategy<Any>()

val items = listOf("Item 1", "Item 2", "Item 3")
val extraItems = listOf("Extra 1", "Extra 2", "Extra 3")

val selectedIndex =
    backStack.lastOrNull()?.let {
        when (it) {
            is DetailKey -> it.index
            is ExtraKey -> it.index
            else -> null
        }
    }

NavDisplay(
    backStack = backStack,
    modifier = Modifier.fillMaxSize(),
    sceneStrategy = sceneStrategy,
    entryProvider =
        entryProvider {
            entry<HomeKey> {
                Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                    Button(
                        onClick = { if (backStack.last() != ListKey) backStack.add(ListKey) }
                    ) {
                        Text("Go to list")
                    }
                }
            }

            entry<ListKey>(
                metadata =
                    ListDetailSceneStrategy.listPane(
                        detailPlaceholder = {
                            DetailPaneContent(selectedItem = null, onShowExtra = {})
                        }
                    )
            ) {
                ListPaneContent(
                    items = items,
                    selectedIndex = selectedIndex,
                    onItemClick = { index ->
                        val dest = DetailKey(index)
                        if (backStack.last() != dest) backStack.add(dest)
                    },
                )
            }

            entry<DetailKey>(metadata = ListDetailSceneStrategy.detailPane()) {
                val scaffoldSceneScope = LocalListDetailSceneScope.current
                DetailPaneContent(
                    selectedItem = selectedIndex?.let { items[it] },
                    onShowExtra = {
                        val dest = ExtraKey(selectedIndex!!)
                        if (backStack.last() != dest) backStack.add(dest)
                    },
                    backButton =
                        if (scaffoldSceneScope == null) {
                            // Only show back button in a single-pane context
                            { BackButton(onClick = { backStack.removeLastOrNull() }) }
                        } else null,
                )
            }

            entry<ExtraKey>(metadata = ListDetailSceneStrategy.extraPane()) {
                val scaffoldSceneScope = LocalListDetailSceneScope.current
                ExtraPaneContent(
                    item = extraItems[selectedIndex!!],
                    backButton =
                        if (scaffoldSceneScope == null) {
                            // Only show back button in a single-pane context
                            { BackButton(onClick = { backStack.removeLastOrNull() }) }
                        } else null,
                )
            }
        },
)
Parameters
shouldHandleSinglePaneLayout: Boolean = false

whether ListDetailSceneStrategy should apply when only a single pane is displayed. By default, this is false and instead yields to the next SceneStrategy in the chain. If true, single pane layouts will instead be handled internally by the Material adaptive scaffold instead of the Navigation 3 system.
backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

the behavior describing which backstack entries may be skipped during the back navigation. See BackNavigationBehavior.
directive: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo())

The top-level directives about how the list-detail scaffold should arrange its panes.
adaptStrategies: ThreePaneScaffoldAdaptStrategies = ListDetailPaneScaffoldDefaults.adaptStrategies()

adaptation strategies of each pane, which denotes how each pane should be adapted if they can't fit on screen in the PaneAdaptedValue.Expanded state. It is recommended to use ListDetailPaneScaffoldDefaults.adaptStrategies as a default, but custom ThreePaneScaffoldAdaptStrategies are supported as well.
paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null

when two panes are displayed side-by-side, a non-null drag handle allows users to resize the panes and change the pane expansion state.
paneExpansionState: PaneExpansionState? = null

the state object of pane expansion. If this is null but a paneExpansionDragHandle is provided, a default implementation will be created.

rememberSupportingPaneSceneStrategy

Cmn 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun <T : Any> rememberSupportingPaneSceneStrategy(
    shouldHandleSinglePaneLayout: Boolean = false,
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilCurrentDestinationChange,
    directive: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo()),
    adaptStrategies: ThreePaneScaffoldAdaptStrategies = SupportingPaneScaffoldDefaults.adaptStrategies(),
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null,
    paneExpansionState: PaneExpansionState? = null
): SupportingPaneSceneStrategy<T>

Creates and remembers a SupportingPaneSceneStrategy.

Parameters
shouldHandleSinglePaneLayout: Boolean = false

whether SupportingPaneSceneStrategy should apply when only a single pane is displayed. By default, this is false and instead yields to the next SceneStrategy in the chain. If true, single pane layouts will instead be handled internally by the Material adaptive scaffold instead of the Navigation 3 system.
backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilCurrentDestinationChange

the behavior describing which backstack entries may be skipped during the back navigation. See BackNavigationBehavior.
directive: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo())

The top-level directives about how the supporting-pane scaffold should arrange its panes.
adaptStrategies: ThreePaneScaffoldAdaptStrategies = SupportingPaneScaffoldDefaults.adaptStrategies()

adaptation strategies of each pane, which denotes how each pane should be adapted if they can't fit on screen in the PaneAdaptedValue.Expanded state. It is recommended to use SupportingPaneScaffoldDefaults.adaptStrategies as a default, but custom ThreePaneScaffoldAdaptStrategies are supported as well.
paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null

when two panes are displayed side-by-side, a non-null drag handle allows users to resize the panes and change the pane expansion state.
paneExpansionState: PaneExpansionState? = null

the state object of pane expansion. If this is null but a paneExpansionDragHandle is provided, a default implementation will be created.

Top-level properties

LocalListDetailSceneScope

Cmn 
@ExperimentalMaterial3AdaptiveApi
val LocalListDetailSceneScope: ProvidableCompositionLocal<ListDetailSceneScope?>

Local provider of ListDetailSceneScope for NavEntrys which are displayed in a Material list-detail scaffold. If null, this means that ListDetailSceneStrategy is not the chosen strategy to display the current content.

LocalSupportingPaneSceneScope

Cmn 
@ExperimentalMaterial3AdaptiveApi
val LocalSupportingPaneSceneScope: ProvidableCompositionLocal<SupportingPaneSceneScope?>

Local provider of SupportingPaneSceneScope for NavEntrys which are displayed in a Material supporting pane scaffold. If null, this means that SupportingPaneSceneStrategy is not the chosen strategy to display the current content.