BottomSheet

Functions summary

Unit

@Composable
@ExperimentalMaterial3Api
BottomSheet(
    modifier: Modifier,
    state: SheetState,
    onDismissRequest: () -> Unit,
    maxWidth: Dp,
    gesturesEnabled: Boolean,
    backHandlerEnabled: Boolean,
    dragHandle: (@Composable () -> Unit)?,
    contentWindowInsets: @Composable () -> WindowInsets,
    shape: Shape,
    containerColor: Color,
    contentColor: Color,
    tonalElevation: Dp,
    shadowElevation: Dp,
    content: @Composable ColumnScope.() -> Unit
)

Material Design bottom sheet

Cmn

Functions

BottomSheet

Cmn

Artifact: androidx.compose.material3:material3

View Source

@Composable
@ExperimentalMaterial3Api
fun BottomSheet(
    modifier: Modifier = Modifier,
    state: SheetState = rememberBottomSheetState(initialValue = Hidden),
    onDismissRequest: () -> Unit = {},
    maxWidth: Dp = BottomSheetDefaults.SheetMaxWidth,
    gesturesEnabled: Boolean = true,
    backHandlerEnabled: Boolean = true,
    dragHandle: (@Composable () -> Unit)? = { BottomSheetDefaults.DragHandle() },
    contentWindowInsets: @Composable () -> WindowInsets = {
        BottomSheetDefaults.standardWindowInsets
    },
    shape: Shape = BottomSheetDefaults.ExpandedShape,
    containerColor: Color = BottomSheetDefaults.ContainerColor,
    contentColor: Color = contentColorFor(containerColor),
    tonalElevation: Dp = BottomSheetDefaults.Elevation,
    shadowElevation: Dp = 0.dp,
    content: @Composable ColumnScope.() -> Unit
): Unit

Material Design bottom sheet

Modal bottom sheets are used as an alternative to inline menus or simple dialogs on mobile, especially when offering a long list of action items, or when items require longer descriptions and icons.

This component provides the visual surface and gesture behavior for a bottom sheet. Crucially, it renders directly in the composition hierarchy (the main UI tree), unlike ModalBottomSheet which launches a separate androidx.compose.ui.window.Dialog window.

Because this component exists in the main UI tree:

It is drawn at the Z-index determined by its placement in the layout (e.g. inside a Box).
It does not automatically provide a scrim or block interaction with the rest of the screen.
It shares the same lifecycle and input handling as its parent composables.

Use this component when building custom sheet experiences where a androidx.compose.ui.window.Dialog window is not desired, or when a custom androidx.compose.ui.window.Dialog is needed.

For a modal bottom sheet that handles the Dialog window, scrim, and focus management automatically, use ModalBottomSheet.

For a persistent bottom sheet that is structurally integrated into a screen layout, use BottomSheetScaffold.

The following sample shows how the component can be used alongside your UI.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.BottomSheet
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scrim
import androidx.compose.material3.SheetValue
import androidx.compose.material3.Text
import androidx.compose.material3.rememberBottomSheetState
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color

var showSheet by remember { mutableStateOf(false) }
Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
    Button(onClick = { showSheet = true }) { Text("Show Manual Sheet") }
}
val sheetState = rememberBottomSheetState(initialValue = SheetValue.Hidden)

if (showSheet) {
    Scrim("scrim", onClick = { showSheet = false })
    BottomSheet(
        modifier = Modifier,
        state = sheetState,
        onDismissRequest = { showSheet = false },
    ) {
        LazyColumn {
            items(25) {
                ListItem(
                    content = { Text("Item $it") },
                    leadingContent = {
                        Icon(
                            Icons.Default.Favorite,
                            contentDescription = "Localized description",
                        )
                    },
                    colors =
                        ListItemDefaults.colors(
                            containerColor = MaterialTheme.colorScheme.surfaceContainerLow
                        ),
                )
            }
        }
    }
}
// Handle sheet animations
LaunchedEffect(showSheet) {
    if (showSheet) {
        sheetState.show()
    } else {
        sheetState.hide()
    }
}

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the bottom sheet.
`state: SheetState = rememberBottomSheetState(initialValue = Hidden)`	The state object managing the sheet's value and offsets.
`onDismissRequest: () -> Unit = {}`	Optional callback invoked when the sheet is swiped to `Hidden`.
`maxWidth: Dp = BottomSheetDefaults.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.
`gesturesEnabled: Boolean = true`	Whether gestures are enabled.
`backHandlerEnabled: Boolean = true`	Whether dismissing via back press and predictive back behavior is enabled
`dragHandle: (@Composable () -> Unit)? = { BottomSheetDefaults.DragHandle() }`	Optional visual marker to indicate the sheet is draggable.
`contentWindowInsets: @Composable () -> WindowInsets = { BottomSheetDefaults.standardWindowInsets }`	Window insets to be applied to the content.
`shape: Shape = BottomSheetDefaults.ExpandedShape`	The shape of the bottom sheet.
`containerColor: Color = BottomSheetDefaults.ContainerColor`	The background color of the bottom sheet.
`contentColor: Color = contentColorFor(containerColor)`	The preferred content color.
`tonalElevation: Dp = BottomSheetDefaults.Elevation`	The tonal elevation of the bottom sheet.
`shadowElevation: Dp = 0.dp`	The shadow elevation of the bottom sheet.
`content: @Composable ColumnScope.() -> Unit`	The content of the sheet.