androidx.compose.material3.adaptive.navigation

Interfaces

ThreePaneScaffoldNavigator

The common interface of the default navigation implementations for different three-pane scaffolds.
Cmn

Classes

BackNavigationBehavior

A class to control how back navigation should behave in a ThreePaneScaffoldNavigator.
Cmn

Top-level functions summary

Unit
@ExperimentalMaterial3AdaptiveApi
@Composable
<T : Any?> NavigableListDetailPaneScaffold(
    navigator: ThreePaneScaffoldNavigator<T>,
    listPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    detailPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    modifier: Modifier,
    extraPane: (@Composable ThreePaneScaffoldPaneScope.() -> Unit)?,
    defaultBackBehavior: BackNavigationBehavior,
    paneMotions: ThreePaneMotion,
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)?,
    paneExpansionState: PaneExpansionState
)

A version of ListDetailPaneScaffold that supports navigation and predictive back handling out of the box, controlled by ThreePaneScaffoldNavigator.
android
Unit
@ExperimentalMaterial3AdaptiveApi
@Composable
<T : Any?> NavigableSupportingPaneScaffold(
    navigator: ThreePaneScaffoldNavigator<T>,
    mainPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    supportingPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    modifier: Modifier,
    extraPane: (@Composable ThreePaneScaffoldPaneScope.() -> Unit)?,
    defaultBackBehavior: BackNavigationBehavior,
    paneMotions: ThreePaneMotion,
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)?,
    paneExpansionState: PaneExpansionState
)

A version of SupportingPaneScaffold that supports navigation and predictive back handling out of the box, controlled by ThreePaneScaffoldNavigator.
android
ThreePaneScaffoldNavigator<Any>
@ExperimentalMaterial3AdaptiveApi
@Composable
rememberListDetailPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective,
    adaptStrategies: ThreePaneScaffoldAdaptStrategies,
    isDestinationHistoryAware: Boolean
)

Returns a remembered default implementation of ThreePaneScaffoldNavigator for ListDetailPaneScaffold, which will be updated automatically when the input values change.
Cmn
ThreePaneScaffoldNavigator<T>
@ExperimentalMaterial3AdaptiveApi
@Composable
<T : Any?> rememberListDetailPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective,
    adaptStrategies: ThreePaneScaffoldAdaptStrategies,
    isDestinationHistoryAware: Boolean,
    initialDestinationHistory: List<ThreePaneScaffoldDestinationItem<T>>
)

Returns a remembered default implementation of ThreePaneScaffoldNavigator for ListDetailPaneScaffold, which will be updated automatically when the input values change.
Cmn
ThreePaneScaffoldNavigator<Any>
@ExperimentalMaterial3AdaptiveApi
@Composable
rememberSupportingPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective,
    adaptStrategies: ThreePaneScaffoldAdaptStrategies,
    isDestinationHistoryAware: Boolean
)

Returns a remembered default implementation of ThreePaneScaffoldNavigator for SupportingPaneScaffold, which will be updated automatically when the input values change.
Cmn
ThreePaneScaffoldNavigator<T>
@ExperimentalMaterial3AdaptiveApi
@Composable
<T : Any?> rememberSupportingPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective,
    adaptStrategies: ThreePaneScaffoldAdaptStrategies,
    isDestinationHistoryAware: Boolean,
    initialDestinationHistory: List<ThreePaneScaffoldDestinationItem<T>>
)

Returns a remembered default implementation of ThreePaneScaffoldNavigator for SupportingPaneScaffold, which will be updated automatically when the input values change.
Cmn

Top-level functions

android 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun <T : Any?> NavigableListDetailPaneScaffold(
    navigator: ThreePaneScaffoldNavigator<T>,
    listPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    detailPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    modifier: Modifier = Modifier,
    extraPane: (@Composable ThreePaneScaffoldPaneScope.() -> Unit)? = null,
    defaultBackBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilContentChange,
    paneMotions: ThreePaneMotion = navigator.scaffoldState.calculateListDetailPaneScaffoldMotion(),
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null,
    paneExpansionState: PaneExpansionState = rememberPaneExpansionState(navigator.scaffoldValue)
): Unit

A version of ListDetailPaneScaffold that supports navigation and predictive back handling out of the box, controlled by ThreePaneScaffoldNavigator.

Parameters
navigator: ThreePaneScaffoldNavigator<T>

The navigator instance to navigate through the scaffold.
listPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit

the list pane of the scaffold, which is supposed to hold a list of item summaries that can be selected from, for example, the inbox mail list of a mail app. See ListDetailPaneScaffoldRole.List.
detailPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit

the detail pane of the scaffold, which is supposed to hold the detailed info of a selected item, for example, the mail content currently being viewed. See ListDetailPaneScaffoldRole.Detail.
modifier: Modifier = Modifier

Modifier of the scaffold layout.
extraPane: (@Composable ThreePaneScaffoldPaneScope.() -> Unit)? = null

the extra pane of the scaffold, which is supposed to hold any supplementary info besides the list and the detail panes, for example, a task list or a mini-calendar view of a mail app. See ListDetailPaneScaffoldRole.Extra.
defaultBackBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilContentChange

the default back navigation behavior when the system back event happens. See BackNavigationBehavior for the use cases of each behavior.
paneMotions: ThreePaneMotion = navigator.scaffoldState.calculateListDetailPaneScaffoldMotion()

The specified motion of the panes. By default the value will be calculated by calculateListDetailPaneScaffoldMotion according to the target ThreePaneScaffoldValue.
paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null

the pane expansion drag handle to let users be able to drag to change pane expansion state. Note that by default this argument will be null, and there won't be a drag handle rendered and users won't be able to drag to change the pane split. You can provide a PaneExpansionDragHandle here as our sample suggests. On the other hand, even if there's no drag handle, you can still modify paneExpansionState directly to apply pane expansion.
paneExpansionState: PaneExpansionState = rememberPaneExpansionState(navigator.scaffoldValue)

the state object of pane expansion.
android 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun <T : Any?> NavigableSupportingPaneScaffold(
    navigator: ThreePaneScaffoldNavigator<T>,
    mainPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    supportingPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit,
    modifier: Modifier = Modifier,
    extraPane: (@Composable ThreePaneScaffoldPaneScope.() -> Unit)? = null,
    defaultBackBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilContentChange,
    paneMotions: ThreePaneMotion = navigator.scaffoldState.calculateSupportingPaneScaffoldMotion(),
    paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null,
    paneExpansionState: PaneExpansionState = rememberPaneExpansionState(navigator.scaffoldValue)
): Unit

A version of SupportingPaneScaffold that supports navigation and predictive back handling out of the box, controlled by ThreePaneScaffoldNavigator.

Parameters
navigator: ThreePaneScaffoldNavigator<T>

The navigator instance to navigate through the scaffold.
mainPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit

the main pane of the scaffold, which is supposed to hold the major content of an app, for example, the editing screen of a doc app. See SupportingPaneScaffoldRole.Main.
supportingPane: @Composable ThreePaneScaffoldPaneScope.() -> Unit

the supporting pane of the scaffold, which is supposed to hold the support content of an app, for example, the comment list of a doc app. See SupportingPaneScaffoldRole.Supporting.
modifier: Modifier = Modifier

Modifier of the scaffold layout.
extraPane: (@Composable ThreePaneScaffoldPaneScope.() -> Unit)? = null

the extra pane of the scaffold, which is supposed to hold any additional content besides the main and the supporting panes, for example, a styling panel in a doc app. See SupportingPaneScaffoldRole.Extra.
defaultBackBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilContentChange

the default back navigation behavior when the system back event happens. See BackNavigationBehavior for the use cases of each behavior.
paneMotions: ThreePaneMotion = navigator.scaffoldState.calculateSupportingPaneScaffoldMotion()

The specified motion of the panes. By default the value will be calculated by calculateSupportingPaneScaffoldMotion according to the target ThreePaneScaffoldValue.
paneExpansionDragHandle: (@Composable ThreePaneScaffoldScope.(PaneExpansionState) -> Unit)? = null

the pane expansion drag handle to let users be able to drag to change pane expansion state. Note that by default this argument will be null, and there won't be a drag handle rendered and users won't be able to drag to change the pane split. You can provide a PaneExpansionDragHandle here as our sample suggests. On the other hand, even if there's no drag handle, you can still modify paneExpansionState directly to apply pane expansion.
paneExpansionState: PaneExpansionState = rememberPaneExpansionState(navigator.scaffoldValue)

the state object of pane expansion.

rememberListDetailPaneScaffoldNavigator

Cmn 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun rememberListDetailPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo()),
    adaptStrategies: ThreePaneScaffoldAdaptStrategies = ListDetailPaneScaffoldDefaults.adaptStrategies(),
    isDestinationHistoryAware: Boolean = true
): ThreePaneScaffoldNavigator<Any>

Returns a remembered default implementation of ThreePaneScaffoldNavigator for ListDetailPaneScaffold, which will be updated automatically when the input values change. The default navigator is supposed to be used independently from any navigation frameworks and handles the navigation purely inside the ListDetailPaneScaffold.

Parameters
scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo())

the current layout directives to follow. The default value will be calculated with calculatePaneScaffoldDirective using WindowAdaptiveInfo retrieved from the current context.
adaptStrategies: ThreePaneScaffoldAdaptStrategies = ListDetailPaneScaffoldDefaults.adaptStrategies()

adaptation strategies of each pane.
isDestinationHistoryAware: Boolean = true

true if the scaffold value calculation should be aware of the full destination history, instead of just the current destination. See calculateThreePaneScaffoldValue for more relevant details.

rememberListDetailPaneScaffoldNavigator

Cmn 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun <T : Any?> rememberListDetailPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo()),
    adaptStrategies: ThreePaneScaffoldAdaptStrategies = ListDetailPaneScaffoldDefaults.adaptStrategies(),
    isDestinationHistoryAware: Boolean = true,
    initialDestinationHistory: List<ThreePaneScaffoldDestinationItem<T>> = DefaultListDetailPaneHistory
): ThreePaneScaffoldNavigator<T>

Returns a remembered default implementation of ThreePaneScaffoldNavigator for ListDetailPaneScaffold, which will be updated automatically when the input values change. The default navigator is supposed to be used independently from any navigation frameworks and handles the navigation purely inside the ListDetailPaneScaffold.

Parameters
<T : Any?>

the type representing the content key/id for a navigation destination. This type must be storable in a Bundle. Used to customize navigation behavior (for example, BackNavigationBehavior). If this customization is unneeded, you can pass Any.
scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo())

the current layout directives to follow. The default value will be calculated with calculatePaneScaffoldDirective using WindowAdaptiveInfo retrieved from the current context.
adaptStrategies: ThreePaneScaffoldAdaptStrategies = ListDetailPaneScaffoldDefaults.adaptStrategies()

adaptation strategies of each pane.
isDestinationHistoryAware: Boolean = true

true if the scaffold value calculation should be aware of the full destination history, instead of just the current destination. See calculateThreePaneScaffoldValue for more relevant details.
initialDestinationHistory: List<ThreePaneScaffoldDestinationItem<T>> = DefaultListDetailPaneHistory

the initial pane destination history of the scaffold, by default it will be just the list pane.

rememberSupportingPaneScaffoldNavigator

Cmn 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun rememberSupportingPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo()),
    adaptStrategies: ThreePaneScaffoldAdaptStrategies = SupportingPaneScaffoldDefaults.adaptStrategies(),
    isDestinationHistoryAware: Boolean = true
): ThreePaneScaffoldNavigator<Any>

Returns a remembered default implementation of ThreePaneScaffoldNavigator for SupportingPaneScaffold, which will be updated automatically when the input values change. The default navigator is supposed to be used independently from any navigation frameworks and handles the navigation purely inside the SupportingPaneScaffold.

Parameters
scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo())

the current layout directives to follow. The default value will be calculated with calculatePaneScaffoldDirective using WindowAdaptiveInfo retrieved from the current context.
adaptStrategies: ThreePaneScaffoldAdaptStrategies = SupportingPaneScaffoldDefaults.adaptStrategies()

adaptation strategies of each pane.
isDestinationHistoryAware: Boolean = true

true if the scaffold value calculation should be aware of the full destination history, instead of just the current destination. See calculateThreePaneScaffoldValue for more relevant details.

rememberSupportingPaneScaffoldNavigator

Cmn 
@ExperimentalMaterial3AdaptiveApi
@Composable
fun <T : Any?> rememberSupportingPaneScaffoldNavigator(
    scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo()),
    adaptStrategies: ThreePaneScaffoldAdaptStrategies = SupportingPaneScaffoldDefaults.adaptStrategies(),
    isDestinationHistoryAware: Boolean = true,
    initialDestinationHistory: List<ThreePaneScaffoldDestinationItem<T>> = DefaultSupportingPaneHistory
): ThreePaneScaffoldNavigator<T>

Returns a remembered default implementation of ThreePaneScaffoldNavigator for SupportingPaneScaffold, which will be updated automatically when the input values change. The default navigator is supposed to be used independently from any navigation frameworks and handles the navigation purely inside the SupportingPaneScaffold.

Parameters
<T : Any?>

the type representing the content key/id for a navigation destination. This type must be storable in a Bundle. Used to customize navigation behavior (for example, BackNavigationBehavior). If this customization is unneeded, you can pass Any.
scaffoldDirective: PaneScaffoldDirective = calculatePaneScaffoldDirective(currentWindowAdaptiveInfo())

the current layout directives to follow. The default value will be calculated with calculatePaneScaffoldDirective using WindowAdaptiveInfo retrieved from the current context.
adaptStrategies: ThreePaneScaffoldAdaptStrategies = SupportingPaneScaffoldDefaults.adaptStrategies()

adaptation strategies of each pane.
isDestinationHistoryAware: Boolean = true

true if the scaffold value calculation should be aware of the full destination history, instead of just the current destination. See calculateThreePaneScaffoldValue for more relevant details.
initialDestinationHistory: List<ThreePaneScaffoldDestinationItem<T>> = DefaultSupportingPaneHistory

the initial destination history of the scaffold, by default it will be just the main pane.