New Compose Multiplatform components arrived on Composables UICheck it out →

← Component in Material 3 Compose

HorizontalMultiBrowseCarousel

Common

A horizontal carousel meant to display many items at once for quick browsing of smaller content like album art or photo thumbnails.

Note that this carousel may adjust the size of items in order to ensure a mix of large, medium, and small items fit perfectly into the available space and are arranged in a visually pleasing way. Carousel then lays out items using the large item size and clips (or masks) items depending on their scroll offset to create items which smoothly expand and collapse between the large, medium, and small sizes.

For more information, see design guidelines.

Last updated:

Installation

dependencies {
   implementation("androidx.compose.material3:material3:1.3.0-beta04")
}

Overloads

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

Parameters

namedescription
stateThe state object to be used to control the carousel's state
preferredItemWidthThe width that large, fully visible items would like to be in the horizontal axis. This width is a target and will likely be adjusted by carousel in order to fit a whole number of items within the container. Carousel adjusts small items first (between the [minSmallItemWidth] and [maxSmallItemWidth]) then medium items when present, and finally large items if necessary.
modifierA modifier instance to be applied to this carousel container
itemSpacingThe amount of space used to separate items in the carousel
flingBehaviorThe [TargetedFlingBehavior] to be used for post scroll gestures
minSmallItemWidthThe minimum allowable width of small items in dp. Depending on the [preferredItemWidth] and the width of the carousel, the small item width will be chosen from a range of [minSmallItemWidth] and [maxSmallItemWidth]
maxSmallItemWidthThe maximum allowable width of small items in dp. Depending on the [preferredItemWidth] and the width of the carousel, the small item width will be chosen from a range of [minSmallItemWidth] and [maxSmallItemWidth]
contentPaddinga 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.
contentThe carousel's content Composable

Code Example

HorizontalMultiBrowseCarouselSample

@Composable
@Sampled
@Preview
@OptIn(ExperimentalMaterial3Api::class
fun HorizontalMultiBrowseCarouselSample() {

    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),
        )

    HorizontalMultiBrowseCarousel(
        state = rememberCarouselState { items.count() },
        modifier = Modifier.width(412.dp).height(221.dp),
        preferredItemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = items[i]
        Image(
            modifier = Modifier.height(205.dp).maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = stringResource(item.contentDescriptionResId),
            contentScale = ContentScale.Crop
        )
    }
}