CarouselState

Artifact: androidx.compose.material3:material3

View Source

Added in 1.3.0

Common/All

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