{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

BottomSheetScaffoldKt

public final class BottomSheetScaffoldKt


Summary

Public methods

static final void
@Composable
@ExperimentalMaterial3Api
BottomSheetScaffold(
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> sheetContent,
    @NonNull Modifier modifier,
    @NonNull BottomSheetScaffoldState scaffoldState,
    @NonNull Dp sheetPeekHeight,
    @NonNull Dp sheetMaxWidth,
    @NonNull Shape sheetShape,
    @NonNull Color sheetContainerColor,
    @NonNull Color sheetContentColor,
    @NonNull Dp sheetTonalElevation,
    @NonNull Dp sheetShadowElevation,
    @Composable Function0<Unit> sheetDragHandle,
    boolean sheetSwipeEnabled,
    @Composable Function0<Unit> topBar,
    @Composable @NonNull Function1<@NonNull SnackbarHostStateUnit> snackbarHost,
    @NonNull Color containerColor,
    @NonNull Color contentColor,
    @Composable @NonNull Function1<@NonNull PaddingValuesUnit> content
)

Material Design standard bottom sheet scaffold.

static final @NonNull BottomSheetScaffoldState

Create and remember a BottomSheetScaffoldState.

static final @NonNull SheetState
@Composable
@ExperimentalMaterial3Api
rememberStandardBottomSheetState(
    @NonNull SheetValue initialValue,
    @NonNull Function1<@NonNull SheetValue, @NonNull Boolean> confirmValueChange,
    boolean skipHiddenState
)

Create and remember a SheetState for BottomSheetScaffold.

Public methods

BottomSheetScaffold

@Composable
@ExperimentalMaterial3Api
public static final void BottomSheetScaffold(
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> sheetContent,
    @NonNull Modifier modifier,
    @NonNull BottomSheetScaffoldState scaffoldState,
    @NonNull Dp sheetPeekHeight,
    @NonNull Dp sheetMaxWidth,
    @NonNull Shape sheetShape,
    @NonNull Color sheetContainerColor,
    @NonNull Color sheetContentColor,
    @NonNull Dp sheetTonalElevation,
    @NonNull Dp sheetShadowElevation,
    @Composable Function0<Unit> sheetDragHandle,
    boolean sheetSwipeEnabled,
    @Composable Function0<Unit> topBar,
    @Composable @NonNull Function1<@NonNull SnackbarHostStateUnit> snackbarHost,
    @NonNull Color containerColor,
    @NonNull Color contentColor,
    @Composable @NonNull Function1<@NonNull PaddingValuesUnit> content
)

Material Design standard bottom sheet scaffold.

Standard bottom sheets co-exist with the screen’s main UI region and allow for simultaneously viewing and interacting with both regions. They are commonly used to keep a feature or secondary content visible on screen when content in main UI region is frequently scrolled or panned.

Bottom sheet image

This component provides API to put together several material components to construct your screen, by ensuring proper layout strategy for them and collecting necessary data so these components will work together correctly.

A simple example of a standard bottom sheet looks like this:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.BottomSheetScaffold
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.material3.rememberBottomSheetScaffoldState
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

val scope = rememberCoroutineScope()
val scaffoldState = rememberBottomSheetScaffoldState()

BottomSheetScaffold(
    scaffoldState = scaffoldState,
    sheetPeekHeight = 128.dp,
    sheetContent = {
        Box(
            Modifier
                .fillMaxWidth()
                .height(128.dp),
            contentAlignment = Alignment.Center
        ) {
            Text("Swipe up to expand sheet")
        }
        Column(
            Modifier
                .fillMaxWidth()
                .padding(64.dp),
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text("Sheet content")
            Spacer(Modifier.height(20.dp))
            Button(
                onClick = {
                    scope.launch { scaffoldState.bottomSheetState.partialExpand() }
                }
            ) {
                Text("Click to collapse sheet")
            }
        }
    }) { innerPadding ->
    Box(
        modifier = Modifier
            .fillMaxSize()
            .padding(innerPadding),
        contentAlignment = Alignment.Center
    ) {
        Text("Scaffold Content")
    }
}
Parameters
@Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> sheetContent

the content of the bottom sheet

@NonNull Modifier modifier

the Modifier to be applied to this scaffold

@NonNull BottomSheetScaffoldState scaffoldState

the state of the bottom sheet scaffold

@NonNull Dp sheetPeekHeight

the height of the bottom sheet when it is collapsed

@NonNull Dp sheetMaxWidth

Dp that defines what the maximum width the sheet will take. Pass in Dp.Unspecified for a sheet that spans the entire screen width.

@NonNull Shape sheetShape

the shape of the bottom sheet

@NonNull Color sheetContainerColor

the background color of the bottom sheet

@NonNull Color sheetContentColor

the preferred content color provided by the bottom sheet to its children. Defaults to the matching content color for sheetContainerColor, or if that is not a color from the theme, this will keep the same content color set above the bottom sheet.

@NonNull Dp sheetTonalElevation

the tonal elevation of the bottom sheet

@NonNull Dp sheetShadowElevation

the shadow elevation of the bottom sheet

@Composable Function0<Unit> sheetDragHandle

optional visual marker to pull the scaffold's bottom sheet

boolean sheetSwipeEnabled

whether the sheet swiping is enabled and should react to the user's input

@Composable Function0<Unit> topBar

top app bar of the screen, typically a SmallTopAppBar

@Composable @NonNull Function1<@NonNull SnackbarHostStateUnit> snackbarHost

component to host Snackbars that are pushed to be shown via SnackbarHostState.showSnackbar, typically a SnackbarHost

@NonNull Color containerColor

the color used for the background of this scaffold. Use Color.Transparent to have no color.

@NonNull Color contentColor

the preferred color for content inside this scaffold. Defaults to either the matching content color for containerColor, or to the current LocalContentColor if containerColor is not a color from the theme.

@Composable @NonNull Function1<@NonNull PaddingValuesUnit> content

content of the screen. The lambda receives a PaddingValues that should be applied to the content root via Modifier.padding and Modifier.consumeWindowInsets to properly offset top and bottom bars. If using Modifier.verticalScroll, apply this modifier to the child of the scroll, and not on the scroll itself.

rememberBottomSheetScaffoldState

@Composable
@ExperimentalMaterial3Api
public static final @NonNull BottomSheetScaffoldState rememberBottomSheetScaffoldState(
    @NonNull SheetState bottomSheetState,
    @NonNull SnackbarHostState snackbarHostState
)

Create and remember a BottomSheetScaffoldState.

Parameters
@NonNull SheetState bottomSheetState

the state of the standard bottom sheet. See rememberStandardBottomSheetState

@NonNull SnackbarHostState snackbarHostState

the SnackbarHostState used to show snackbars inside the scaffold

rememberStandardBottomSheetState

@Composable
@ExperimentalMaterial3Api
public static final @NonNull SheetState rememberStandardBottomSheetState(
    @NonNull SheetValue initialValue,
    @NonNull Function1<@NonNull SheetValue, @NonNull Boolean> confirmValueChange,
    boolean skipHiddenState
)

Create and remember a SheetState for BottomSheetScaffold.

Parameters
@NonNull SheetValue initialValue

the initial value of the state. Should be either PartiallyExpanded or Expanded if skipHiddenState is true

@NonNull Function1<@NonNull SheetValue, @NonNull Boolean> confirmValueChange

optional callback invoked to confirm or veto a pending state change

boolean skipHiddenState

whether Hidden state is skipped for BottomSheetScaffold