# ModalBottomSheet

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/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)( onDismissRequest: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, sheetState: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState, sheetMaxWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, sheetGesturesEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, 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, scrimColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, 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, properties: https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalBottomSheetProperties, 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 modal bottom sheet](https://m3.material.io/components/bottom-sheets/overview) | Cmn |

## Functions

### ModalBottomSheet

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/ModalBottomSheet.kt+function:ModalBottomSheet)

```
@Composable
@ExperimentalMaterial3Api
fun ModalBottomSheet(
    onDismissRequest: () -> Unit,
    modifier: Modifier = Modifier,
    sheetState: SheetState = rememberBottomSheetState(initialValue = Hidden),
    sheetMaxWidth: Dp = BottomSheetDefaults.SheetMaxWidth,
    sheetGesturesEnabled: Boolean = true,
    shape: Shape = BottomSheetDefaults.ExpandedShape,
    containerColor: Color = BottomSheetDefaults.ContainerColor,
    contentColor: Color = contentColorFor(containerColor),
    tonalElevation: Dp = 0.dp,
    scrimColor: Color = BottomSheetDefaults.ScrimColor,
    dragHandle: (@Composable () -> Unit)? = { BottomSheetDefaults.DragHandle() },
    contentWindowInsets: @Composable () -> WindowInsets = { BottomSheetDefaults.modalWindowInsets },
    properties: ModalBottomSheetProperties = ModalBottomSheetProperties(),
    content: @Composable ColumnScope.() -> Unit
): Unit
```

[Material Design modal 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. Like dialogs, modal bottom sheets appear in front of app content, disabling all other app functionality when they appear, and remaining on screen until confirmed, dismissed, or a required action has been taken.

![Bottom sheet
image](https://developer.android.com/images/reference/androidx/compose/material3/bottom_sheet.png)

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

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.selection.toggleable
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.Checkbox
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.ModalBottomSheet
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SheetValue
import androidx.compose.material3.Text
import androidx.compose.material3.rememberBottomSheetState
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.unit.dp

var openBottomSheet by rememberSaveable { mutableStateOf(false) }
var skipPartiallyExpanded by rememberSaveable { mutableStateOf(false) }
val scope = rememberCoroutineScope()
val bottomSheetState =
    rememberBottomSheetState(
        initialValue = SheetValue.Hidden,
        enabledValues =
            if (skipPartiallyExpanded) setOf(SheetValue.Hidden, SheetValue.Expanded)
            else setOf(SheetValue.Hidden, SheetValue.PartiallyExpanded, SheetValue.Expanded),
    )

// App content
Column(
    horizontalAlignment = Alignment.Start,
    verticalArrangement = Arrangement.spacedBy(4.dp),
) {
    Row(
        Modifier.toggleable(
            value = skipPartiallyExpanded,
            role = Role.Checkbox,
            onValueChange = { checked -> skipPartiallyExpanded = checked },
        )
    ) {
        Checkbox(checked = skipPartiallyExpanded, onCheckedChange = null)
        Spacer(Modifier.width(16.dp))
        Text("Skip partially expanded State")
    }
    Button(
        onClick = { openBottomSheet = !openBottomSheet },
        modifier = Modifier.align(Alignment.CenterHorizontally),
    ) {
        Text(text = "Show Bottom Sheet")
    }
}

// Sheet content
if (openBottomSheet) {

    ModalBottomSheet(
        onDismissRequest = { openBottomSheet = false },
        sheetState = bottomSheetState,
    ) {
        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.Center) {
            Button(
                // Note: If you provide logic outside of onDismissRequest to remove the sheet,
                // you must additionally handle intended state cleanup, if any.
                onClick = {
                    scope
                        .launch { bottomSheetState.hide() }
                        .invokeOnCompletion {
                            if (!bottomSheetState.isVisible) {
                                openBottomSheet = false
                            }
                        }
                }
            ) {
                Text("Hide Bottom Sheet")
            }
        }
        var text by remember { mutableStateOf("") }
        OutlinedTextField(
            value = text,
            onValueChange = { text = it },
            modifier = Modifier.padding(horizontal = 16.dp),
            label = { Text("Text field") },
        )
        LazyColumn {
            items(25) {
                ListItem(
                    content = { Text("Item $it") },
                    leadingContent = {
                        Icon(
                            Icons.Default.Favorite,
                            contentDescription = "Localized description",
                        )
                    },
                    colors =
                        ListItemDefaults.colors(
                            containerColor = MaterialTheme.colorScheme.surfaceContainerLow
                        ),
                )
            }
        }
    }
}
```

| Parameters |
|---|---|
| `onDismissRequest: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | Executes when the user clicks outside of the bottom sheet, after sheet animates to `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue#Hidden`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | Optional `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` for the bottom sheet. |
| `sheetState: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState = rememberBottomSheetState(initialValue = Hidden)` | The state of the bottom sheet. |
| `sheetMaxWidth: 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. |
| `sheetGesturesEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Whether the bottom sheet can be interacted with by gestures. |
| `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 color used for the background of this bottom sheet |
| `contentColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = contentColorFor(containerColor)` | The preferred color for content inside this bottom sheet. Defaults to either the matching content color for `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#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)`, or to the current `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#LocalContentColor()` if `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#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)` is not a color from the theme. |
| `tonalElevation: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = 0.dp` | when `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#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)` is `https://developer.android.com/reference/kotlin/androidx/compose/material3/ColorScheme#surface()`, a translucent primary color overlay is applied on top of the container. A higher tonal elevation value will result in a darker color in light theme and lighter color in dark theme. See also: `https://developer.android.com/reference/kotlin/androidx/compose/material3/Surface.composable#Surface(androidx.compose.ui.Modifier,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,androidx.compose.foundation.BorderStroke,kotlin.Function0)`. |
| `scrimColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = BottomSheetDefaults.ScrimColor` | Color of the scrim that obscures content when the bottom sheet is open. |
| `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 swipe the bottom sheet. |
| `contentWindowInsets: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/WindowInsets = { BottomSheetDefaults.modalWindowInsets }` | callback which provides window insets to be passed to the bottom sheet content via `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/windowInsetsPadding.modifier#(androidx.compose.ui.Modifier).windowInsetsPadding(androidx.compose.foundation.layout.WindowInsets)`. `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)` will pre-emptively consume top insets based on it's current offset. This keeps content outside of the expected window insets at any position. By default, IME padding is handled through this parameter as part of the window insets. If the IME padding is required from a different scope (e.g. a different window opens a keyboard then launches `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)`), then `Modifier.imePadding` should be applied to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#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)` parameter. |
| `properties: https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalBottomSheetProperties = ModalBottomSheetProperties()` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalBottomSheetProperties` for further customization of this modal bottom sheet's window behavior. |
| `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 to be displayed inside the bottom sheet. |