CarouselState

Class

Common

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

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

Parameters


currentItem	the current item to be scrolled to.
currentItemOffsetFraction	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	the number of items this Carousel will have.

Properties

Common

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 PagerState.currentPage for more information.

Functions

suspend fun scrollToItem(item: Int) = pagerState.scrollToPage(item, 0f)

Scroll (jump immediately) to a given item.

Parameters


item	The destination item to scroll to

suspend fun animateScrollToItem(item: Int, animationSpec: AnimationSpec<Float> = spring()) =
        with(pagerState) {
            if ((item == currentPage && currentPageOffsetFraction == 0f) || pageCount == 0) {
                return
            }

            val targetPage = if (pageCount > 0) item.coerceIn(0, pageCount - 1) else 0
            scroll {
                LazyLayoutScrollScope(this@with, this)
                    .animateScrollToPage(
                        pagerState = this@with,
                        targetPage = targetPage,
                        targetPageOffsetToSnappedPosition = 0f,
                        animationSpec = animationSpec,
                        updateTargetPage = { updateTargetPage(it) },
                    )
            }
        }

Scroll animate to a given item. If the item is too far away from 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.

Parameters


item	the index of the item to scroll to with an animation
animationSpec	an `AnimationSpec` used to scroll between the items.

Companion Object

Properties

Common

val Saver: Saver<CarouselState, *>

To keep current item and item offset saved