CarouselState

Artifact: androidx.compose.material3:material3

Added in 1.3.0

Cmn

@ExperimentalMaterial3Api
class CarouselState : ScrollableState

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

Summary

Public companion properties
`Saver<CarouselState, *>`	`Saver` To keep current item and item offset saved	Cmn

Public constructors
`CarouselState( currentItem: Int, currentItemOffsetFraction: @FloatRange(from = -0.5, to = 0.5) Float, itemCount: () -> Int )`	Cmn

Public functions
`suspend Unit`	`animateScrollToItem(item: Int, animationSpec: AnimationSpec<Float>)` Scroll animate to a given `item`.	Cmn
`open Float`	`dispatchRawDelta(delta: Float)` Dispatch scroll delta in pixels avoiding all scroll related mechanisms.	Cmn
`open suspend Unit`	`scroll(scrollPriority: MutatePriority, block: suspend ScrollScope.() -> Unit)` Call this function to take control of scrolling and gain the ability to send scroll events via `ScrollScope.scrollBy`.	Cmn
`suspend Unit`	`scrollToItem(item: Int)` Scroll (jump immediately) to a given `item`.	Cmn

Public properties
`Int`	`currentItem` The item that sits closest to the snapped position.	Cmn
`open Boolean`	`isScrollInProgress` Whether this `ScrollableState` is currently scrolling by gesture, fling or programmatically or not.	Cmn

Inherited properties

From androidx.compose.foundation.gestures.ScrollableState

`open Boolean`	`canScrollBackward` Whether this `ScrollableState` can scroll backward (consume a negative delta).	Cmn
`open Boolean`	`canScrollForward` Whether this `ScrollableState` can scroll forward (consume a positive delta).	Cmn
`open Boolean`	`lastScrolledBackward` The value of this property is true under the following scenarios, otherwise it's false.	Cmn
`open Boolean`	`lastScrolledForward` The value of this property is true under the following scenarios, otherwise it's false.	Cmn

Public companion properties

Saver

Cmn

Added in 1.3.0

val Saver: Saver<CarouselState, *>

To keep current item and item offset saved

Public constructors

CarouselState

Cmn

Added in 1.3.0

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

Parameters
`currentItem: Int = 0`	the current item to be scrolled to.
`currentItemOffsetFraction: @FloatRange(from = -0.5, to = 0.5) Float = 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: () -> Int`	the number of items this Carousel will have.

Public functions

animateScrollToItem

Cmn

Added in 1.4.0-alpha16

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

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.

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: Int`	the index of the item to scroll to with an animation
`animationSpec: AnimationSpec<Float> = spring()`	an `AnimationSpec` used to scroll between the items.

dispatchRawDelta

Cmn

Added in 1.3.0

open fun dispatchRawDelta(delta: Float): Float

Dispatch scroll delta in pixels avoiding all scroll related mechanisms.

NOTE: unlike scroll, 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 ScrollableState influence the consumption as suits them. Manually dispatching delta via this method will likely result in a bad user experience, you must prefer scroll method over this one.

Parameters
`delta: Float`	amount of scroll dispatched in the nested scroll process

Returns
`Float`	the amount of delta consumed

scroll

Cmn

Added in 1.3.0

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

Call this function to take control of scrolling and gain the ability to send scroll events via ScrollScope.scrollBy. All actions that change the logical scroll position must be performed within a scroll block (even if they don't call any other methods on this object) in order to guarantee that mutual exclusion is enforced.

If scroll is called from elsewhere with the scrollPriority higher or equal to ongoing scroll, ongoing scroll will be canceled.

scrollToItem

Cmn

Added in 1.4.0-alpha16

suspend fun scrollToItem(item: Int): Unit

Scroll (jump immediately) to a given item.

Parameters
`item: Int`	The destination item to scroll to

Public properties

currentItem

Cmn

Added in 1.4.0-alpha16

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.

isScrollInProgress

Cmn

Added in 1.3.0

open val isScrollInProgress: Boolean

Whether this ScrollableState is currently scrolling by gesture, fling or programmatically or not.