State of a sheet composable, such as ModalBottomSheet

Contains states relating to its swipe position as well as animations between state values.

Summary

Public companion functions

Saver<SheetStateSheetValue>
Saver(
    skipPartiallyExpanded: Boolean,
    confirmValueChange: (SheetValue) -> Boolean,
    density: Density,
    skipHiddenState: Boolean
)

The default Saver implementation for SheetState.

Cmn

Public constructors

SheetState(
    skipPartiallyExpanded: Boolean,
    density: Density,
    initialValue: SheetValue,
    confirmValueChange: (SheetValue) -> Boolean,
    skipHiddenState: Boolean
)
Cmn

Public functions

suspend Unit

Fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled.

Cmn
suspend Unit

Hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled.

Cmn
suspend Unit

Animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled.

Cmn
Float

Require the current offset (in pixels) of the bottom sheet.

Cmn
suspend Unit

Expand the bottom sheet with animation and suspend until it is PartiallyExpanded if defined else Expanded.

Cmn

Public properties

SheetValue

The current value of the state.

Cmn
Boolean

Whether the sheet has an expanded state defined.

Cmn
Boolean

Whether the modal bottom sheet has a partially expanded state defined.

Cmn
Boolean

Whether the modal bottom sheet is visible.

Cmn
SheetValue

The target value of the bottom sheet state.

Cmn

Public companion functions

Saver

fun Saver(
    skipPartiallyExpanded: Boolean,
    confirmValueChange: (SheetValue) -> Boolean,
    density: Density,
    skipHiddenState: Boolean
): Saver<SheetStateSheetValue>

The default Saver implementation for SheetState.

Public constructors

SheetState

SheetState(
    skipPartiallyExpanded: Boolean,
    density: Density,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true },
    skipHiddenState: Boolean = false
)
Parameters
skipPartiallyExpanded: Boolean

Whether the partially expanded state, if the sheet is large enough, should be skipped. If true, the sheet will always expand to the Expanded state and move to the Hidden state if available when hiding the sheet, either programmatically or by user interaction.

density: Density

The density that this state can use to convert values to and from dp.

initialValue: SheetValue = Hidden

The initial value of the state.

confirmValueChange: (SheetValue) -> Boolean = { true }

Optional callback invoked to confirm or veto a pending state change.

skipHiddenState: Boolean = false

Whether the hidden state should be skipped. If true, the sheet will always expand to the Expanded state and move to the PartiallyExpanded if available, either programmatically or by user interaction.

Public functions

expand

suspend fun expand(): Unit

Fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled.

Throws
kotlinx.coroutines.CancellationException

if the animation is interrupted

hide

suspend fun hide(): Unit

Hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled.

Throws
kotlinx.coroutines.CancellationException

if the animation is interrupted

partialExpand

suspend fun partialExpand(): Unit

Animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled.

Throws
kotlinx.coroutines.CancellationException

if the animation is interrupted

kotlin.IllegalStateException

if skipPartiallyExpanded is set to true

requireOffset

fun requireOffset(): Float

Require the current offset (in pixels) of the bottom sheet.

The offset will be initialized during the first measurement phase of the provided sheet content.

These are the phases: Composition { -> Effects } -> Layout { Measurement -> Placement } -> Drawing

During the first composition, an IllegalStateException is thrown. In subsequent compositions, the offset will be derived from the anchors of the previous pass. Always prefer accessing the offset from a LaunchedEffect as it will be scheduled to be executed the next frame, after layout.

Throws
kotlin.IllegalStateException

If the offset has not been initialized yet

show

suspend fun show(): Unit

Expand the bottom sheet with animation and suspend until it is PartiallyExpanded if defined else Expanded.

Throws
kotlinx.coroutines.CancellationException

if the animation is interrupted

Public properties

currentValue

val currentValueSheetValue

The current value of the state.

If no swipe or animation is in progress, this corresponds to the state the bottom sheet is currently in. If a swipe or an animation is in progress, this corresponds the state the sheet was in before the swipe or animation started.

hasExpandedState

val hasExpandedStateBoolean

Whether the sheet has an expanded state defined.

hasPartiallyExpandedState

val hasPartiallyExpandedStateBoolean

Whether the modal bottom sheet has a partially expanded state defined.

isVisible

val isVisibleBoolean

Whether the modal bottom sheet is visible.

targetValue

val targetValueSheetValue

The target value of the bottom sheet state.

If a swipe is in progress, this is the value that the sheet would animate to if the swipe finishes. If an animation is running, this is the target value of that animation. Finally, if no swipe or animation is in progress, this is the same as the currentValue.