HorizontalCenteredHeroCarousel

Composable Component

A horizontal carousel that centers one large item between two small items.

Common

@ExperimentalMaterial3Api
@Composable
fun HorizontalCenteredHeroCarousel(
    state: CarouselState,
    modifier: Modifier = Modifier,
    maxItemWidth: Dp = Dp.Unspecified,
    itemSpacing: Dp = 0.dp,
    flingBehavior: TargetedFlingBehavior =
        CarouselDefaults.singleAdvanceFlingBehavior(state = state),
    userScrollEnabled: Boolean = true,
    minSmallItemWidth: Dp = CarouselDefaults.MinSmallItemSize,
    maxSmallItemWidth: Dp = CarouselDefaults.MaxSmallItemSize,
    contentPadding: PaddingValues = PaddingValues(0.dp),
    content: @Composable CarouselItemScope.(itemIndex: Int) -> Unit,
)

Parameters


state	The state object to be used to control the carousel's state
modifier	A modifier instance to be applied to this carousel container
maxItemWidth	The max width a large item is allowed to be in dp. The default value of `Dp.Unspecified` allows one large item to grow to fill the entire viewport minus space for two surrounding small items. Values other than unspecified will add additional large items as space allows.
itemSpacing	The amount of space used to separate items in the carousel
flingBehavior	The `TargetedFlingBehavior` to be used for post scroll gestures
userScrollEnabled	whether the scrolling via the user gestures or accessibility actions is allowed.
minSmallItemWidth	The minimum allowable width of small items in dp
maxSmallItemWidth	The maximum allowable width of small items in dp
contentPadding	a padding around the whole content. This will add padding for the content after it has been clipped. You can use it to add a padding before the first item or after the last one. Use `itemSpacing` to add spacing between the items.
content	The carousel's content Composable

Code Examples

HorizontalCenteredHeroCarouselSample

@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun HorizontalCenteredHeroCarouselSample() {
    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,
        )
    }
}