SheetState

Class

Common

@ExperimentalMaterial3Api
class SheetState(
    internal val skipPartiallyExpanded: Boolean,
    positionalThreshold: () -> Float,
    velocityThreshold: () -> Float,
    initialValue: SheetValue = Hidden,
    internal val confirmValueChange: (SheetValue) -> Boolean = { true },
    internal val skipHiddenState: Boolean = false,
)

State of a sheet composable, such as ModalBottomSheet

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

Parameters


skipPartiallyExpanded	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.
positionalThreshold	The positional threshold, in px, to be used when calculating the target state while a drag is in progress and when settling after the drag ends. This is the distance from the start of a transition. It will be, depending on the direction of the interaction, added or subtracted from/to the origin offset. It should always be a positive value.
velocityThreshold	The velocity threshold (in px per second) that the end velocity has to exceed in order to animate to the next state, even if the `positionalThreshold` has not been reached.
initialValue	The initial value of the state.
confirmValueChange	Optional callback invoked to confirm or veto a pending state change.
skipHiddenState	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.

Secondary Constructors

constructor(
    skipPartiallyExpanded: Boolean,
    density: Density,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true },
    skipHiddenState: Boolean = false,
) : this(
    skipPartiallyExpanded = skipPartiallyExpanded,
    positionalThreshold = { with(density) { BottomSheetDefaults.PositionalThreshold.toPx() } },
    velocityThreshold = { with(density) { BottomSheetDefaults.VelocityThreshold.toPx() } },
    initialValue = initialValue,
    confirmValueChange = confirmValueChange,
    skipHiddenState = skipHiddenState,
)

Properties

Common

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.

Common

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.

Common

val isVisible: Boolean

Whether the modal bottom sheet is visible.

Common

val isAnimationRunning: Boolean

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

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

Common

val hasExpandedState: Boolean

Whether the sheet has an expanded state defined.

Common

val hasPartiallyExpandedState: Boolean

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

Functions

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.

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.

suspend fun partialExpand()

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

suspend fun show()

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

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

Common

fun Saver(
            skipPartiallyExpanded: Boolean,
            positionalThreshold: () -> Float,
            velocityThreshold: () -> Float,
            confirmValueChange: (SheetValue) -> Boolean,
            skipHiddenState: Boolean,
        ) =
            Saver<SheetState, SheetValue>(
                save = { it.currentValue },
                restore = { savedValue ->
                    SheetState(
                        skipPartiallyExpanded,
                        positionalThreshold,
                        velocityThreshold,
                        savedValue,
                        confirmValueChange,
                        skipHiddenState,
                    )
                },
            )

The default Saver implementation for SheetState.

Common

Deprecated Maintained for binary compatibility.

fun Saver(
            skipPartiallyExpanded: Boolean,
            confirmValueChange: (SheetValue) -> Boolean,
            density: Density,
            skipHiddenState: Boolean,
        ) =
            Saver(
                skipPartiallyExpanded = skipPartiallyExpanded,
                confirmValueChange = confirmValueChange,
                skipHiddenState = skipHiddenState,
                positionalThreshold = {
                    with(density) { BottomSheetDefaults.PositionalThreshold.toPx() }
                },
                velocityThreshold = {
                    with(density) { BottomSheetDefaults.VelocityThreshold.toPx() }
                },
            )