# CarouselState

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/carousel/CarouselState.kt+class:androidx.compose.material3.carousel.CarouselState) Common/All
- Cmn

  ```
  class CarouselState : ScrollableState
  ```

*** ** * ** ***

The state that can be used to control all types of carousels.

## Summary

| ### Public companion properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/saveable/Saver<https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState, *>` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#Saver()` To keep current item and item offset saved | Cmn |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#CarouselState(kotlin.Int,kotlin.Float,kotlin.Function0)( currentItem: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, currentItemOffsetFraction: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = -0.5, to = 0.5) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, itemCount: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` | Cmn |

| ### Public functions |
|---|---|---|
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#animateScrollToItem(kotlin.Int,androidx.compose.animation.core.AnimationSpec)(item: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, animationSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/core/AnimationSpec<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>)` Scroll animate to a given `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#animateScrollToItem(kotlin.Int,androidx.compose.animation.core.AnimationSpec)`. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#dispatchRawDelta(kotlin.Float)(delta: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` Dispatch scroll delta in pixels avoiding all scroll related mechanisms. | Cmn |
| `open suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#scroll(androidx.compose.foundation.MutatePriority,kotlin.coroutines.SuspendFunction1)(scrollPriority: https://developer.android.com/reference/kotlin/androidx/compose/foundation/MutatePriority, block: suspend https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Call this function to take control of scrolling and gain the ability to send scroll events via `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollScope#scrollBy(kotlin.Float)`. | Cmn |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#scrollToItem(kotlin.Int)(item: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Scroll (jump immediately) to a given `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#scrollToItem(kotlin.Int)`. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#currentItem()` The item that sits closest to the snapped position. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#isScrollInProgress()` Whether this `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` is currently scrolling by gesture, fling or programmatically or not. | Cmn |

### Inherited properties

From [androidx.compose.foundation.gestures.ScrollableState](https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState) `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#canScrollBackward()`

Whether this `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` can scroll backward (consume a negative delta).
Cmn `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#canScrollForward()`

Whether this `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` can scroll forward (consume a positive delta).
Cmn `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#lastScrolledBackward()`

The value of this property is true under the following scenarios, otherwise it's false.
Cmn `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#lastScrolledForward()`

The value of this property is true under the following scenarios, otherwise it's false.
Cmn `open https://developer.android.com/reference/kotlin/androidx/compose/foundation/ScrollIndicatorState?` `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#scrollIndicatorState()`

`https://developer.android.com/reference/kotlin/androidx/compose/foundation/ScrollIndicatorState` used for drawing a scroll indicator (e.g., a scrollbar).
Cmn

## Public companion properties

### Saver

Cmn

```
val Saver: Saver<CarouselState, *>
```

To keep current item and item offset saved

## Public constructors

### CarouselState

Cmn

```
CarouselState(
    currentItem: Int = 0,
    currentItemOffsetFraction: @FloatRange(from = -0.5, to = 0.5) Float = 0.0f,
    itemCount: () -> Int
)
```

| Parameters |
|---|---|
| `currentItem: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = 0` | the current item to be scrolled to. |
| `currentItemOffsetFraction: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = -0.5, to = 0.5) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = 0.0f` | the offset of the current item as a fraction of the item's size. This should vary between -0.5 and 0.5 and indicates how to offset the current item from the snapped position. |
| `itemCount: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | the number of items this Carousel will have. |

## Public functions

### animateScrollToItem

Cmn

```
suspend fun animateScrollToItem(
    item: Int,
    animationSpec: AnimationSpec<Float> = spring()
): Unit
```

Scroll animate to a given `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#animateScrollToItem(kotlin.Int,androidx.compose.animation.core.AnimationSpec)`. If the `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#animateScrollToItem(kotlin.Int,androidx.compose.animation.core.AnimationSpec)` is too far away from `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#currentItem()`, Carousel will avoid composing all intermediate items by jumping to a nearer item before animating the scroll.

Please refer to the sample to learn how to use this API.

```kotlin
import androidx.annotation.DrawableRes
import androidx.annotation.StringRes
import androidx.compose.foundation.Image
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.filled.Image
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.carousel.HorizontalCenteredHeroCarousel
import androidx.compose.material3.carousel.rememberCarouselState
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.unit.dp

data class CarouselItem(
    val id: Int,
    @DrawableRes val imageResId: Int,
    @StringRes val contentDescriptionResId: Int,
)

val items =
    listOf(
        CarouselItem(0, R.drawable.carousel_image_1, R.string.carousel_image_1_description),
        CarouselItem(1, R.drawable.carousel_image_2, R.string.carousel_image_2_description),
        CarouselItem(2, R.drawable.carousel_image_3, R.string.carousel_image_3_description),
        CarouselItem(3, R.drawable.carousel_image_4, R.string.carousel_image_4_description),
        CarouselItem(4, R.drawable.carousel_image_5, R.string.carousel_image_5_description),
    )
val state = rememberCarouselState { items.count() }
val animationScope = rememberCoroutineScope()
HorizontalCenteredHeroCarousel(
    state = state,
    modifier = Modifier.fillMaxWidth().height(221.dp).padding(horizontal = 24.dp),
    itemSpacing = 8.dp,
    contentPadding = PaddingValues(horizontal = 16.dp),
) { i ->
    val item = items[i]
    Image(
        modifier =
            Modifier.fillMaxWidth()
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge)
                .clickable(true, "Tap to focus", Role.Image) {
                    animationScope.launch { state.animateScrollToItem(i) }
                },
        painter = painterResource(id = item.imageResId),
        contentDescription = stringResource(item.contentDescriptionResId),
        contentScale = ContentScale.Crop,
    )
}
```

| Parameters |
|---|---|
| `item: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | the index of the item to scroll to with an animation |
| `animationSpec: https://developer.android.com/reference/kotlin/androidx/compose/animation/core/AnimationSpec<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html> = spring()` | an `https://developer.android.com/reference/kotlin/androidx/compose/animation/core/AnimationSpec` used to scroll between the items. |

### dispatchRawDelta

Cmn

```
open fun dispatchRawDelta(delta: Float): Float
```

Dispatch scroll delta in pixels avoiding all scroll related mechanisms.

**NOTE:** unlike `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#scroll(androidx.compose.foundation.MutatePriority,kotlin.coroutines.SuspendFunction1)`, dispatching any delta with this method won't trigger nested scroll, won't stop ongoing scroll/drag animation and will bypass scrolling of any priority. This method will also ignore `reverseDirection` and other parameters set in scrollable.

This method is used internally for nested scrolling dispatch and other low level operations, allowing implementers of `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` influence the consumption as suits them. Manually dispatching delta via this method will likely result in a bad user experience, you must prefer `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#scroll(androidx.compose.foundation.MutatePriority,kotlin.coroutines.SuspendFunction1)` method over this one.

| Parameters |
|---|---|
| `delta: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | amount of scroll dispatched in the nested scroll process |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | the amount of delta consumed |

### scroll

Cmn

```
open suspend fun scroll(
    scrollPriority: MutatePriority = MutatePriority.Default,
    block: suspend ScrollScope.() -> Unit
): Unit
```

Call this function to take control of scrolling and gain the ability to send scroll events via `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollScope#scrollBy(kotlin.Float)`. All actions that change the logical scroll position must be performed within a `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#scroll(androidx.compose.foundation.MutatePriority,kotlin.coroutines.SuspendFunction1)` block (even if they don't call any other methods on this object) in order to guarantee that mutual exclusion is enforced.

If `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#scroll(androidx.compose.foundation.MutatePriority,kotlin.coroutines.SuspendFunction1)` is called from elsewhere with the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState#scroll(androidx.compose.foundation.MutatePriority,kotlin.coroutines.SuspendFunction1)` higher or equal to ongoing scroll, ongoing scroll will be canceled.

### scrollToItem

Cmn

```
suspend fun scrollToItem(item: Int): Unit
```

Scroll (jump immediately) to a given `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState#scrollToItem(kotlin.Int)`.

| Parameters |
|---|---|
| `item: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The destination item to scroll to |

## Public properties

### currentItem

Cmn

```
val currentItem: Int
```

The item that sits closest to the snapped position. This is an observable value and will change as the carousel scrolls either by gesture or animation.

Please refer to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/pager/PagerState#currentPage()` for more information.

### isScrollInProgress

Cmn

```
open val isScrollInProgress: Boolean
```

Whether this `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` is currently scrolling by gesture, fling or programmatically or not.