Compose Unstyled

Modal Bottom Sheet

A dismissible modal bottom sheet with custom detents.

View Markdown

Deprecated

Modal Bottom Sheet will be removed in Compose Unstyled 3.0. Use Drawer instead. See Migrating to Drawer.

ModalBottomSheetDemo.kt
@file:Suppress("DEPRECATION")

package com.composeunstyled.demo.modalbottomsheet

import androidx.compose.animation.fadeIn
import androidx.compose.animation.fadeOut
import androidx.compose.foundation.LocalIndication
import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.heightIn
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.widthIn
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import com.composeunstyled.DragIndication
import com.composeunstyled.Scrim
import com.composeunstyled.Sheet
import com.composeunstyled.SheetDetent
import com.composeunstyled.SheetDetent.Companion.FullyExpanded
import com.composeunstyled.SheetDetent.Companion.Hidden
import com.composeunstyled.Text
import com.composeunstyled.UnstyledButton
import com.composeunstyled.UnstyledModalBottomSheet
import com.composeunstyled.demo.DemoColors
import com.composeunstyled.rememberModalBottomSheetState
import com.composeunstyled.theme.Theme

@Preview
@Composable
fun ModalBottomSheetDemo() {
  val Peek = SheetDetent("peek") { containerHeight, _ ->
    containerHeight * 0.6f
  }
  val modalSheetState = rememberModalBottomSheetState(
    initialDetent = Peek,
    detents = listOf(Hidden, Peek, FullyExpanded),
  )

  Box(
    modifier = Modifier.fillMaxSize(),
    contentAlignment = Alignment.Center,
  ) {
    UnstyledButton(
      onClick = { modalSheetState.targetDetent = Peek },
      modifier = Modifier
        .heightIn(32.dp)
        .background(Theme.get<DemoColors>().surface)
        .border(1.dp, Theme.get<DemoColors>().border),
      contentPadding = PaddingValues(horizontal = 10.dp),
      indication = LocalIndication.current,
    ) {
      Text("Show bottom sheet")
    }

    UnstyledModalBottomSheet(
      state = modalSheetState,
      overlay = {
        Scrim(
          scrimColor = Theme.get<DemoColors>().scrim,
          enter = fadeIn(),
          exit = fadeOut(),
        )
      },
    ) {
      Box(
        modifier = Modifier
          .fillMaxWidth(),
        contentAlignment = Alignment.TopCenter,
      ) {
        Sheet(
          modifier = Modifier
            .widthIn(max = 640.dp)
            .fillMaxWidth()
            .background(Theme.get<DemoColors>().surface)
            .border(1.dp, Theme.get<DemoColors>().border),
        ) {
          Box(
            modifier = Modifier.fillMaxWidth().height(1000.dp),
            contentAlignment = Alignment.TopCenter,
          ) {
            DragIndication(
              modifier = Modifier
                .padding(top = 22.dp)
                .background(Theme.get<DemoColors>().border)
                .size(32.dp, 4.dp),
              indication = LocalIndication.current,
            )
          }
        }
      }
    }
  }
}

Features

  • Custom detents
  • Custom overlay content
  • Back press and outside click dismissal
  • Dynamic content sizing
  • Soft-keyboard support
  • Scrollable content without fixed height

Installation

implementation("com.composables:composeunstyled-modal-bottom-sheet:2.10.2")

Anatomy

val sheetState = rememberModalBottomSheetState(
  initialDetent = SheetDetent.Hidden,
)

UnstyledModalBottomSheet(state = sheetState) {
  Sheet {
    DragIndication()
  }
}

Concepts

  • SheetDetent defines a height where the sheet can rest.
  • UnstyledModalBottomSheet represents the modal layer the sheet is rendered in.
  • Sheet is the rendered bit of the sheet.
  • DragIndication adds an interactive handle for expand, collapse, and dismiss actions.

Accessibility

Use DragIndication when your sheet can move between multiple detents. It provides semantic expand, collapse, and dismiss actions so users can control the sheet without dragging.

Code Examples

Showing and hiding a modal bottom sheet

Use the targetDetent property to animate the modal sheet to a new detent:

val sheetState = rememberModalBottomSheetState(
  initialDetent = SheetDetent.Hidden,
)

BasicText(
  text = "Show sheet",
  modifier = Modifier.clickable {
    sheetState.targetDetent = SheetDetent.FullyExpanded
  },
)

UnstyledModalBottomSheet(state = sheetState) {
  Sheet {
    BasicText(
      text = "Hide sheet",
      modifier = Modifier.clickable {
        sheetState.targetDetent = SheetDetent.Hidden
      },
    )
  }
}

Waiting for modal bottom sheet animations

Use the suspend animateTo() function to wait until the sheet animation is done:

val scope = rememberCoroutineScope()

BasicText(
  text = "Show sheet",
  modifier = Modifier.clickable {
    scope.launch {
      sheetState.animateTo(SheetDetent.FullyExpanded)
    }
  },
)

Opening a modal bottom sheet instantly

Use the jumpTo() function to move to a detent without animation:

BasicText(
  text = "Open immediately",
  modifier = Modifier.clickable {
    sheetState.jumpTo(SheetDetent.FullyExpanded)
  },
)

Adding an overlay behind a modal bottom sheet

Use the overlay parameter to render content behind the modal sheet. Scrim provides a ready-made overlay for modal bottom sheets.

UnstyledModalBottomSheet(
  state = sheetState,
  overlay = { Scrim() },
) {
  Sheet {
    BasicText("Sheet content")
  }
}

Creating modal bottom sheets with custom detents

Use the SheetDetent constructor to create a new detent. Pass a unique identifier and a function that calculates the detent height. The calculated height cannot be smaller than 0.dp, taller than the container, or taller than the sheet content.

Keep this calculation fast. It runs during sheet measurement.

val Peek = SheetDetent("peek") { containerHeight, sheetHeight ->
  minOf(containerHeight * 0.4f, sheetHeight)
}

val sheetState = rememberModalBottomSheetState(
  initialDetent = SheetDetent.Hidden,
  detents = listOf(SheetDetent.Hidden, Peek, SheetDetent.FullyExpanded),
)

Updating modal bottom sheet detents after layout changes

Use the invalidateDetents() function to recalculate sheet detents. This is useful when a custom detent reads a measured value that can change, such as a header height:

var peekHeight by remember { mutableStateOf(120.dp) }

val Peek = remember {
  SheetDetent("peek") { _, _ -> peekHeight }
}

val sheetState = rememberModalBottomSheetState(
  initialDetent = Peek,
  detents = listOf(Peek, SheetDetent.FullyExpanded),
)

LaunchedEffect(peekHeight) {
  sheetState.invalidateDetents()
}

Building modal bottom sheets with scrollable content

Use a scrollable layout inside the Sheet component to make content scroll within the current detent height:

Moving a modal bottom sheet above the soft keyboard

Use the offsetForIme parameter on ModalBottomSheetProperties to automatically move the sheet above the soft keyboard:

val textState = rememberTextFieldState()

UnstyledModalBottomSheet(
  state = sheetState,
  properties = ModalBottomSheetProperties(offsetForIme = true),
) {
  Sheet {
    BasicTextField(state = textState)
  }
}

Disabling back press and outside click dismissal

Use the properties parameter to control how the modal sheet can be dismissed:

UnstyledModalBottomSheet(
  state = sheetState,
  properties = ModalBottomSheetProperties(
    dismissOnBackPress = false,
    dismissOnClickOutside = false,
  ),
) {
  Sheet {
    BasicText("Sheet content")
  }
}

Reacting to modal bottom sheet dismissal

Use the onDismiss parameter to run code when the sheet is dismissed:

UnstyledModalBottomSheet(
  state = sheetState,
  onDismiss = { selectedItem = null },
) {
  Sheet {
    BasicText("Sheet content")
  }
}

Customizing modal bottom sheet animation between detents

Use the animationSpec parameter to customize the default animation between detents. Use the dismissAnimationSpec parameter to customize the animation used when the modal sheet is dismissed:

val sheetState = rememberModalBottomSheetState(
  initialDetent = SheetDetent.Hidden,
  animationSpec = tween(durationMillis = 300),
  dismissAnimationSpec = tween(durationMillis = 180),
)

Migrating to Drawer

A modal UnstyledDrawer placed at the bottom replaces UnstyledModalBottomSheet. These are the drawer’s default placement and presentation. Replace the dependency with composeunstyled-drawer:

implementation("com.composables:composeunstyled-drawer:2.10.2")

Modal Bottom Sheet Drawer
UnstyledModalBottomSheet(state) UnstyledDrawer(state)
ModalBottomSheetHost { } Not needed. Modal drawers do not need a host
rememberModalBottomSheetState(initialDetent, detents) remember { UnstyledDrawerState(initialValue, snapPoints) }
SheetDetent Your own value type, mapped in DrawerSnapPoints { }
SheetDetent.Hidden DrawerSnapPoint.Zero
SheetDetent.FullyExpanded DrawerSnapPoint.ContentSize
SheetDetent("id") { containerHeight, sheetHeight -> } DrawerSnapPoint { viewportSize, contentSize -> }
Sheet { } Viewport { Panel { } }
DragIndication() DragHandle() inside Panel
overlay = { Scrim() } overlay = { Overlay(Modifier.fillMaxSize().background(scrimColor)) }
enabled gesturesEnabled
ModalBottomSheetProperties(dismissOnBackPress) dismissOnNavigateBack
ModalBottomSheetProperties(dismissOnClickOutside) dismissOnClickOutside
ModalBottomSheetProperties(offsetForIme = true) Viewport(windowInsets = WindowInsets.ime)
onDismiss: () -> Unit onDismissed: (DrawerValueChange<T>) -> Unit
currentDetent / targetDetent currentValue / targetValue
animateTo() / jumpTo() animateTo() / jumpTo()
invalidateDetents() invalidateSnapPoints()
animationSpec / dismissAnimationSpec animationSpec / dismissAnimationSpec on UnstyledDrawerState
confirmDetentChange: (SheetDetent) -> Boolean confirmValueChange: (DrawerValueChange<T>) -> Boolean
velocityThreshold, positionalThreshold, decayAnimationSpec No equivalent

Before:

val sheetState = rememberModalBottomSheetState(
  initialDetent = SheetDetent.Hidden,
)

UnstyledModalBottomSheet(
  state = sheetState,
  overlay = { Scrim(enter = fadeIn(), exit = fadeOut()) },
  onDismiss = { selectedItem = null },
) {
  Sheet {
    DragIndication()
  }
}

After:

enum class SheetValue { Hidden, Expanded }

val drawerState = remember {
  UnstyledDrawerState(
    initialValue = SheetValue.Hidden,
    snapPoints = DrawerSnapPoints {
      SheetValue.Hidden at DrawerSnapPoint.Zero
      SheetValue.Expanded at DrawerSnapPoint.ContentSize
    },
  )
}

UnstyledDrawer(
  state = drawerState,
  overlay = {
    Overlay(
      modifier = Modifier.fillMaxSize().background(Color.Black.copy(alpha = 0.6f)),
      enter = fadeIn(),
      exit = fadeOut(),
    )
  },
  onDismissed = { selectedItem = null },
) {
  Viewport(windowInsets = WindowInsets.ime) {
    Panel {
      DragHandle()
    }
  }
}

API Reference

rememberModalBottomSheetState

Parameter Type Description
returns Unit

ModalBottomSheetState

Parameter Type Description
currentDetent SheetDetent The SheetDetent in which the sheet is currently rested on. Setting a new detent will cause the sheet to animate to that detent.
targetDetent SheetDetent The SheetDetent in which the sheet is about to rest on, if it is being dragged or animated.
isIdle Boolean Whether the sheet is currently resting at a specific detent.
offset Float The current offset of the sheet.
fun progress() (SheetDetent, SheetDetent) -> Float
suspend fun animateTo() suspend (SheetDetent) -> Unit Animates the sheet to the given detent. This is a suspend function, which you can use to wait until the animation is complete.
fun jumpTo() (SheetDetent) -> Unit Makes the sheet to immediately appear to the given detent without any animation.
fun invalidateDetents() () -> Unit

UnstyledModalBottomSheet

Parameter Type Description
returns Unit

ModalBottomSheetOverlayScope.Scrim

Parameter Type Description
returns Unit

ModalBottomSheetScope.Sheet

Parameter Type Description
returns Unit

ModalBottomSheetScope.DragIndication

Parameter Type Description
returns Unit