Bottom sheet

A surface anchored to the bottom edge for secondary content and actions.

Category: Containment
API status: Stable
Compose APIs: ModalBottomSheet, BottomSheetScaffold, rememberModalBottomSheetState, BottomSheetDefaults
Interactive page: https://m3e.ljzapps.app/#components/bottom-sheet

When to use

A modal bottom sheet blocks the screen behind a scrim and is dismissed by swiping down, tapping the scrim or pressing Escape. A standard bottom sheet lives beside the content and stays visible while the user keeps working.

On wide windows prefer a side sheet or a dialog, because a full width bottom sheet reads poorly.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Modal

Open it and drag or tap outside to close.

var open by rememberSaveable { mutableStateOf(false) }
val sheetState = rememberModalBottomSheetState()

Button(onClick = { open = true }) { Text("Share options") }

if (open) {
    ModalBottomSheet(
        onDismissRequest = { open = false },
        sheetState = sheetState,
        dragHandle = { BottomSheetDefaults.DragHandle() },
    ) {
        Column(Modifier.padding(bottom = 32.dp)) {
            listOf("Copy link", "Send as message", "Save to files").forEach { label ->
                ListItem(headlineContent = { Text(label) })
            }
        }
    }
}

Standard

Drag the handle up. The content stays interactive.

Box(Modifier.fillMaxWidth().height(380.dp)) {
    BottomSheetScaffold(
        sheetPeekHeight = 96.dp,
        sheetContent = {
            Column(Modifier.fillMaxWidth().padding(bottom = 24.dp)) {
                Text("Now playing", Modifier.padding(horizontal = 24.dp, vertical = 8.dp))
                listOf("Queue", "Lyrics", "Related").forEach { label ->
                    ListItem(headlineContent = { Text(label) })
                }
            }
        },
    ) {
        Box(Modifier.fillMaxWidth().padding(24.dp)) { Text("Content behind the sheet") }
    }
}

Parameters

Name	Type	Default	Description
`onDismissRequest`	`() -> Unit`		Called when the sheet should close.
`sheetState`	`SheetState`	`rememberModalBottomSheetState()`	Controls expansion. skipPartiallyExpanded jumps straight to full height.
`dragHandle`	`@Composable (() -> Unit)?`	`DragHandle()`	Set to null to hide the handle.
`sheetMaxWidth`	`Dp`	`BottomSheetDefaults.SheetMaxWidth`	Limits the width on large windows.

Guidelines

Do:

Use for short lists of actions or supporting detail.
Provide a visible close path.

Don't:

Do not place primary content only in a sheet.
Do not stack sheets.

Accessibility

The drag handle has actions for expand and collapse, so the sheet works without gestures.
A modal sheet traps focus and returns it to the trigger on close.