SheetState

@ExperimentalMaterial3Api
class SheetState
internal constructor(
    internal val enabledValues: Set<SheetValue>,
    internal val positionalThreshold: () -> Float,
    internal val velocityThreshold: () -> Float,
    initialValue: SheetValue,
    internal val confirmValueChange: (SheetValue) -> Boolean,
    internal val isBottomSheetPartiallyExpandedDeterministicEnabled: Boolean,
)

State of a sheet composable, such as ModalBottomSheet

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

Parameters

Secondary Constructors

constructor(
    enabledValues: Set<SheetValue>,
    positionalThreshold: () -> Float,
    velocityThreshold: () -> Float,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true },
) : this(
    enabledValues = enabledValues,
    positionalThreshold = positionalThreshold,
    velocityThreshold = velocityThreshold,
    initialValue = initialValue,
    confirmValueChange = confirmValueChange,
    isBottomSheetPartiallyExpandedDeterministicEnabled =
        ComposeMaterial3Flags.isBottomSheetPartiallyExpandedDeterministicEnabled,
)

State of a sheet composable, such as ModalBottomSheet

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

Parameters

constructor(
    skipPartiallyExpanded: Boolean,
    positionalThreshold: () -> Float,
    velocityThreshold: () -> Float,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true },
    skipHiddenState: Boolean = false,
) : this(
    enabledValues =
        buildSet {
            add(Expanded)
            if (!skipPartiallyExpanded) add(PartiallyExpanded)
            if (!skipHiddenState) add(Hidden)
        },
    positionalThreshold = positionalThreshold,
    velocityThreshold = velocityThreshold,
    initialValue = initialValue,
    confirmValueChange = confirmValueChange,
    isBottomSheetPartiallyExpandedDeterministicEnabled = false,
)

constructor(
    skipPartiallyExpanded: Boolean,
    density: Density,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true },
    skipHiddenState: Boolean = false,
) : this(
    enabledValues =
        buildSet {
            add(Expanded)
            if (!skipPartiallyExpanded) add(PartiallyExpanded)
            if (!skipHiddenState) add(Hidden)
        },
    positionalThreshold = { with(density) { BottomSheetDefaults.PositionalThreshold.toPx() } },
    velocityThreshold = { with(density) { BottomSheetDefaults.VelocityThreshold.toPx() } },
    initialValue = initialValue,
    confirmValueChange = confirmValueChange,
    isBottomSheetPartiallyExpandedDeterministicEnabled = false,
)

Properties

currentValue

val currentValue: SheetValue

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.

targetValue

val targetValue: SheetValue

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.

isVisible

val isVisible: Boolean

Whether the modal bottom sheet is visible.

isAnimationRunning

val isAnimationRunning: Boolean

Whether an expanding or collapsing sheet animation is currently in progress.

See expand, partialExpand, show or hide for more information.

hasExpandedState

val hasExpandedState: Boolean

Whether the sheet has an expanded state defined.

hasPartiallyExpandedState

val hasPartiallyExpandedState: Boolean

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

Functions

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.

expand

suspend fun expand()

If confirmValueChange returns true, fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled.

partialExpand

suspend fun partialExpand()

If confirmValueChange returns true, animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled.

show

suspend fun show()

If confirmValueChange returns true, expand the bottom sheet with animation and suspend until it is PartiallyExpanded if defined, else Expanded.

hide

suspend fun hide()

If confirmValueChange returns true, hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled.

Companion Object

Methods

fun Saver(
            enabledValues: Set<SheetValue>,
            positionalThreshold: () -> Float,
            velocityThreshold: () -> Float,
            confirmValueChange: (SheetValue) -> Boolean,
        ): Saver<SheetState, SheetValue>

The default Saver implementation for SheetState.

fun Saver(
            skipPartiallyExpanded: Boolean,
            positionalThreshold: () -> Float,
            velocityThreshold: () -> Float,
            confirmValueChange: (SheetValue) -> Boolean,
            skipHiddenState: Boolean,
        ) =
            Saver(
                enabledValues =
                    buildSet {
                        add(Expanded)
                        if (!skipPartiallyExpanded) add(PartiallyExpanded)
                        if (!skipHiddenState) add(Hidden)
                    },
                positionalThreshold = positionalThreshold,
                velocityThreshold = velocityThreshold,
                confirmValueChange = confirmValueChange,
                isBottomSheetPartiallyExpandedDeterministicEnabled = false,
            )

fun Saver(
            skipPartiallyExpanded: Boolean,
            confirmValueChange: (SheetValue) -> Boolean,
            density: Density,
            skipHiddenState: Boolean,
        ) =
            Saver(
                enabledValues =
                    buildSet {
                        add(Expanded)
                        if (!skipPartiallyExpanded) add(PartiallyExpanded)
                        if (!skipHiddenState) add(Hidden)
                    },
                confirmValueChange = confirmValueChange,
                positionalThreshold = {
                    with(density) { BottomSheetDefaults.PositionalThreshold.toPx() }
                },
                velocityThreshold = {
                    with(density) { BottomSheetDefaults.VelocityThreshold.toPx() }
                },
                isBottomSheetPartiallyExpandedDeterministicEnabled = false,
            )