# SheetState

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/SheetDefaults.kt+class:androidx.compose.material3.SheetState) Common/AllAndroid/JVM
- Cmn

  ```
  @ExperimentalMaterial3Api
  class SheetState
  ```

*** ** * ** ***

State of a sheet composable, such as `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)`

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

## Summary

| ### Public companion functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/saveable/Saver<https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState, https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue>` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#Saver(kotlin.collections.Set,kotlin.Function0,kotlin.Function0,kotlin.Function1)( enabledValues: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue>, positionalThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, velocityThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, confirmValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` The default `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#Saver(kotlin.collections.Set,kotlin.Function0,kotlin.Function0,kotlin.Function1)` implementation for `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/saveable/Saver<https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState, https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue>` | `[Saver](https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#Saver(kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function1,kotlin.Boolean))( skipPartiallyExpanded: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, positionalThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, velocityThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, confirmValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, skipHiddenState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` **This function is deprecated.** Use the Saver that takes a set of enabled values. | Cmn |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#SheetState(kotlin.collections.Set,kotlin.Function0,kotlin.Function0,androidx.compose.material3.SheetValue,kotlin.Function1)( enabledValues: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue>, positionalThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, velocityThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, initialValue: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue, confirmValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` State of a sheet composable, such as `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)` | Cmn |
| `[SheetState](https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#SheetState(kotlin.Boolean,kotlin.Function0,kotlin.Function0,androidx.compose.material3.SheetValue,kotlin.Function1,kotlin.Boolean))( skipPartiallyExpanded: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, positionalThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, velocityThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, initialValue: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue, confirmValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, skipHiddenState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` **This function is deprecated.** Use the primary constructor that takes a set of enabled values. | Cmn |

| ### Public functions |
|---|---|---|
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#expand()()` If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled. | Cmn |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#hide()()` If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled. | Cmn |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#partialExpand()()` If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#requireOffset()()` Require the current offset (in pixels) of the bottom sheet. | Cmn |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#show()()` If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, expand the bottom sheet with animation and suspend until it is `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue#PartiallyExpanded` if defined, else `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue#Expanded`. | Cmn |

| ### Public properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#currentValue()` The current value of the state. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#hasExpandedState()` Whether the sheet has an expanded state defined. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#hasPartiallyExpandedState()` Whether the modal bottom sheet has a partially expanded state defined. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#isAnimationRunning()` Whether an expanding or collapsing sheet animation is currently in progress. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#isVisible()` Whether the modal bottom sheet is visible. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#targetValue()` The target value of the bottom sheet state. | Cmn |

## Public companion functions

### Saver

Cmn

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

The default `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#Saver(kotlin.collections.Set,kotlin.Function0,kotlin.Function0,kotlin.Function1)` implementation for `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState`.

### Saver

Cmn

```
fun [Saver](https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#Saver(kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function1,kotlin.Boolean))(
    skipPartiallyExpanded: Boolean,
    positionalThreshold: () -> Float,
    velocityThreshold: () -> Float,
    confirmValueChange: (SheetValue) -> Boolean,
    skipHiddenState: Boolean
): Saver<SheetState, SheetValue>
```

> [!CAUTION]
> **This function is deprecated.**   
> Use the Saver that takes a set of enabled values, use this instead:
>
> ```kotlin
> Saver(enabledValues = buildSet { add(SheetValue.Expanded); if (!skipPartiallyExpanded) add(SheetValue.PartiallyExpanded); if (!skipHiddenState) add(SheetValue.Hidden) }, positionalThreshold, velocityThreshold, confirmValueChange)
> ```

## Public constructors

### SheetState

Cmn

```
SheetState(
    enabledValues: Set<SheetValue>,
    positionalThreshold: () -> Float,
    velocityThreshold: () -> Float,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true }
)
```

State of a sheet composable, such as `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)`

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

| Parameters |
|---|---|
| `enabledValues: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue>` | The set of `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue`s that the bottom sheet can settle in. This is the direct source of truth for available states; if a value is included here, the component will attempt to create an anchor for it. |
| `positionalThreshold: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | 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: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#(kotlin.collections.Set,kotlin.Function0,kotlin.Function0,androidx.compose.material3.SheetValue,kotlin.Function1)` has not been reached. |
| `initialValue: https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue = Hidden` | The initial value of the state. |
| `confirmValueChange: (https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = { true }` | Optional callback invoked to confirm or veto a pending state change. |

### SheetState

Cmn

```
[SheetState](https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#SheetState(kotlin.Boolean,kotlin.Function0,kotlin.Function0,androidx.compose.material3.SheetValue,kotlin.Function1,kotlin.Boolean))(
    skipPartiallyExpanded: Boolean,
    positionalThreshold: () -> Float,
    velocityThreshold: () -> Float,
    initialValue: SheetValue = Hidden,
    confirmValueChange: (SheetValue) -> Boolean = { true },
    skipHiddenState: Boolean = false
)
```

> [!CAUTION]
> **This function is deprecated.**   
> Use the primary constructor that takes a set of enabled values, use this instead:
>
> ```kotlin
> SheetState(enabledValues = buildSet { add(SheetValue.Expanded); if (!skipPartiallyExpanded) add(SheetValue.PartiallyExpanded); if (!skipHiddenState) add(SheetValue.Hidden) }, positionalThreshold, velocityThreshold, initialValue, confirmValueChange)
> ```

## Public functions

### expand

Cmn

```
suspend fun expand(): Unit
```

If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled.

| Throws |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html` | if the animation is interrupted |

### hide

Cmn

```
suspend fun hide(): Unit
```

If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled.

| Throws |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html` | if the animation is interrupted |

### partialExpand

Cmn

```
suspend fun partialExpand(): Unit
```

If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled.

| Throws |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html` | if the animation is interrupted |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#skipPartiallyExpanded()` is set to true |

### requireOffset

Cmn

```
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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` 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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If the offset has not been initialized yet |

### show

Cmn

```
suspend fun show(): Unit
```

If `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#confirmValueChange()` returns true, expand the bottom sheet with animation and suspend until it is `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue#PartiallyExpanded` if defined, else `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetValue#Expanded`.

| Throws |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html` | if the animation is interrupted |

## Public properties

### currentValue

Cmn

```
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.

### hasExpandedState

Cmn

```
val hasExpandedState: Boolean
```

Whether the sheet has an expanded state defined.

### hasPartiallyExpandedState

Cmn

```
val hasPartiallyExpandedState: Boolean
```

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

### isAnimationRunning

Cmn

```
val isAnimationRunning: Boolean
```

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

See `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#expand()`, `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#partialExpand()`, `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#show()` or `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#hide()` for more information.

### isVisible

Cmn

```
val isVisible: Boolean
```

Whether the modal bottom sheet is visible.

### targetValue

Cmn

```
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 `https://developer.android.com/reference/kotlin/androidx/compose/material3/SheetState#currentValue()`.