New Compose Multiplatform components arrived on Composables UICheck it out →

← Component in Material Compose

BackdropScaffold

Common

A backdrop appears behind all other surfaces in an app, displaying contextual and actionable content.

Backdrop image

Last updated:

Installation

dependencies {
   implementation("androidx.compose.material:material:1.7.0-beta04")
}

Overloads

@Composable
@OptIn(ExperimentalMaterialApi::class
fun BackdropScaffold(
    appBar: @Composable () -> Unit,
    backLayerContent: @Composable () -> Unit,
    frontLayerContent: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    scaffoldState: BackdropScaffoldState = rememberBackdropScaffoldState(Concealed),
    snackbarHost: @Composable (SnackbarHostState) -> Unit = { SnackbarHost(it) },
    gesturesEnabled: Boolean = true,
    peekHeight: Dp = BackdropScaffoldDefaults.PeekHeight,
    headerHeight: Dp = BackdropScaffoldDefaults.HeaderHeight,
    persistentAppBar: Boolean = true,
    stickyFrontLayer: Boolean = true,
    backLayerBackgroundColor: Color = MaterialTheme.colors.primary,
    backLayerContentColor: Color = contentColorFor(backLayerBackgroundColor),
    frontLayerShape: Shape = BackdropScaffoldDefaults.frontLayerShape,
    frontLayerElevation: Dp = BackdropScaffoldDefaults.FrontLayerElevation,
    frontLayerBackgroundColor: Color = MaterialTheme.colors.surface,
    frontLayerContentColor: Color = contentColorFor(frontLayerBackgroundColor),
    frontLayerScrimColor: Color = BackdropScaffoldDefaults.frontLayerScrimColor,
)

Parameters

namedescription
appBarApp bar for the back layer. Make sure that the [peekHeight] is equal to the height of the app bar, so that the app bar is fully visible. Consider using [TopAppBar] but set the elevation to 0dp and background color to transparent as a surface is already provided.
backLayerContentThe content of the back layer.
frontLayerContentThe content of the front layer.
modifierOptional [Modifier] for the root of the scaffold.
scaffoldStateThe state of the scaffold.
snackbarHostThe component hosting the snackbars shown inside the scaffold.
gesturesEnabledWhether or not the backdrop can be interacted with by gestures.
peekHeightThe height of the visible part of the back layer when it is concealed.
headerHeightThe minimum height of the front layer when it is inactive.
persistentAppBarWhether the app bar should be shown when the back layer is revealed. By default, it will always be shown above the back layer's content. If this is set to false, the back layer will automatically switch between the app bar and its content with an animation.
stickyFrontLayerWhether the front layer should stick to the height of the back layer.
backLayerBackgroundColorThe background color of the back layer.
backLayerContentColorThe preferred content color provided by the back layer to its children. Defaults to the matching content color for [backLayerBackgroundColor], or if that is not a color from the theme, this will keep the same content color set above the back layer.
frontLayerShapeThe shape of the front layer.
frontLayerElevationThe elevation of the front layer.
frontLayerBackgroundColorThe background color of the front layer.
frontLayerContentColorThe preferred content color provided by the back front to its children. Defaults to the matching content color for [frontLayerBackgroundColor], or if that is not a color from the theme, this will keep the same content color set above the front layer.
frontLayerScrimColorThe color of the scrim applied to the front layer when the back layer is revealed. If the color passed is [Color.Unspecified], then a scrim will not be applied and interaction with the front layer will not be blocked when the back layer is revealed.

Code Example

BackdropScaffoldSample

@OptIn(ExperimentalMaterialApi::class
@Composable
@Sampled
fun BackdropScaffoldSample() {
    val scope = rememberCoroutineScope()
    val selection = remember { mutableStateOf(1) }
    val scaffoldState = rememberBackdropScaffoldState(BackdropValue.Concealed)
    LaunchedEffect(scaffoldState) {
        scaffoldState.reveal()
    }
    BackdropScaffold(
        scaffoldState = scaffoldState,
        appBar = {
            TopAppBar(
                title = { Text("Backdrop scaffold") },
                navigationIcon = {
                    if (scaffoldState.isConcealed) {
                        IconButton(onClick = { scope.launch { scaffoldState.reveal() } }) {
                            Icon(Icons.Default.Menu, contentDescription = "Localized description")
                        }
                    } else {
                        IconButton(onClick = { scope.launch { scaffoldState.conceal() } }) {
                            Icon(Icons.Default.Close, contentDescription = "Localized description")
                        }
                    }
                },
                actions = {
                    var clickCount by remember { mutableStateOf(0) }
                    IconButton(
                        onClick = {
                            // show snackbar as a suspend function
                            scope.launch {
                                scaffoldState.snackbarHostState
                                    .showSnackbar("Snackbar #${++clickCount}")
                            }
                        }
                    ) {
                        Icon(Icons.Default.Favorite, contentDescription = "Localized description")
                    }
                },
                elevation = 0.dp,
                backgroundColor = Color.Transparent
            )
        },
        backLayerContent = {
            LazyColumn {
                items(if (selection.value >= 3) 3 else 5) {
                    ListItem(
                        Modifier.clickable {
                            selection.value = it
                            scope.launch { scaffoldState.conceal() }
                        },
                        text = { Text("Select $it") }
                    )
                }
            }
        },
        frontLayerContent = {
            Text("Selection: ${selection.value}")
            LazyColumn {
                items(50) {
                    ListItem(
                        text = { Text("Item $it") },
                        icon = {
                            Icon(
                                Icons.Default.Favorite,
                                contentDescription = "Localized description"
                            )
                        }
                    )
                }
            }
        }
    )
}