# BottomSheet

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable @https://developer.android.com/reference/kotlin/androidx/compose/material3/ExperimentalMaterial3Api https://developer.android.com/reference/kotlin/androidx/compose/material3/BottomSheet.composable#BottomSheet(androidx.compose.ui.Modifier,androidx.compose.material3.SheetState,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Boolean,kotlin.Boolean,kotlin.Function0,kotlin.Function0,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,kotlin.Function1)( modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, state: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState, onDismissRequest: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, maxWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, gesturesEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, backHandlerEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, dragHandle: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, contentWindowInsets: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/WindowInsets, shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape, containerColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, contentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, tonalElevation: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, shadowElevation: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/ColumnScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` [Material Design bottom sheet](https://m3.material.io/components/bottom-sheets/overview) | Cmn |

## Functions

### BottomSheet

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/BottomSheet.kt+function:BottomSheet)

```
@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](https://m3.material.io/components/bottom-sheets/overview)

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 `https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalBottomSheet.composable#ModalBottomSheet(kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.material3.SheetState,androidx.compose.ui.unit.Dp,kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.graphics.Color,kotlin.Function0,kotlin.Function0,androidx.compose.material3.ModalBottomSheetProperties,kotlin.Function1)` which launches a separate `https://developer.android.com/reference/kotlin/androidx/compose/ui/window/Dialog.composable#Dialog(kotlin.Function0,androidx.compose.ui.window.DialogProperties,kotlin.Function0)` 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Box.composable#Box(androidx.compose.ui.Modifier,androidx.compose.ui.Alignment,kotlin.Boolean,kotlin.Function1)`).

- 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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/window/Dialog.composable#Dialog(kotlin.Function0,androidx.compose.ui.window.DialogProperties,kotlin.Function0)` window is not desired, or when a custom `https://developer.android.com/reference/kotlin/androidx/compose/ui/window/Dialog.composable#Dialog(kotlin.Function0,androidx.compose.ui.window.DialogProperties,kotlin.Function0)` is needed.

For a modal bottom sheet that handles the Dialog window, scrim, and focus management automatically, use `https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalBottomSheet.composable#ModalBottomSheet(kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.material3.SheetState,androidx.compose.ui.unit.Dp,kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.graphics.Color,kotlin.Function0,kotlin.Function0,androidx.compose.material3.ModalBottomSheetProperties,kotlin.Function1)`.

For a persistent bottom sheet that is structurally integrated into a screen layout, use `https://developer.android.com/reference/kotlin/androidx/compose/material3/BottomSheetScaffold.composable#BottomSheetScaffold(kotlin.Function1,androidx.compose.ui.Modifier,androidx.compose.material3.BottomSheetScaffoldState,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,kotlin.Function0,kotlin.Boolean,kotlin.Function0,kotlin.Function1,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Function1)`.

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

```kotlin
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: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | The modifier to be applied to the bottom sheet. |
| `state: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState = rememberBottomSheetState(initialValue = Hidden)` | The state object managing the sheet's value and offsets. |
| `onDismissRequest: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Optional callback invoked when the sheet is swiped to `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue#Hidden`. |
| `maxWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = BottomSheetDefaults.SheetMaxWidth` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp` that defines what the maximum width the sheet will take. Pass in `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp#Unspecified()` for a sheet that spans the entire screen width. |
| `gesturesEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Whether gestures are enabled. |
| `backHandlerEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Whether dismissing via back press and predictive back behavior is enabled |
| `dragHandle: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = { BottomSheetDefaults.DragHandle() }` | Optional visual marker to indicate the sheet is draggable. |
| `contentWindowInsets: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/WindowInsets = { BottomSheetDefaults.standardWindowInsets }` | Window insets to be applied to the content. |
| `shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape = BottomSheetDefaults.ExpandedShape` | The shape of the bottom sheet. |
| `containerColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = BottomSheetDefaults.ContainerColor` | The background color of the bottom sheet. |
| `contentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = contentColorFor(containerColor)` | The preferred content color. |
| `tonalElevation: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = BottomSheetDefaults.Elevation` | The tonal elevation of the bottom sheet. |
| `shadowElevation: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = 0.dp` | The shadow elevation of the bottom sheet. |
| `content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/ColumnScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The content of the sheet. |