Carousel
Scrolling collections of items whose sizes change as they move through the viewport.
- Category: Containment
- API status: Expressive
- Compose APIs:
HorizontalMultiBrowseCarousel,HorizontalUncontainedCarousel,HorizontalCenteredHeroCarousel,rememberCarouselState - Interactive page: https://m3e.ljzapps.app/#components/carousel
When to use
Multi-browse shows one large item next to medium and small ones, which suits browsing many items. Uncontained keeps every item at one size and lets the last one peek in. Center hero focuses a single item.
Clip each item with maskClip so the item shrinks and grows with the carousel instead of being cut off.
Playground
The interactive page has a playground with live property controls for this component and generated code.
Examples
Multi-browse
Drag or scroll horizontally.
val colors = itemColors()
HorizontalMultiBrowseCarousel(
state = rememberCarouselState { Titles.size },
preferredItemWidth = 186.dp,
itemSpacing = 8.dp,
modifier = Modifier.fillMaxWidth(),
) { index ->
CarouselItemBox(Titles[index], colors[index], Modifier.maskClip(MaterialTheme.shapes.extraLarge))
}
Uncontained
val colors = itemColors()
HorizontalUncontainedCarousel(
state = rememberCarouselState { Titles.size },
itemWidth = 200.dp,
itemSpacing = 8.dp,
modifier = Modifier.fillMaxWidth(),
) { index ->
CarouselItemBox(Titles[index], colors[index], Modifier.maskClip(MaterialTheme.shapes.extraLarge))
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
state | CarouselState | Create with rememberCarouselState { itemCount }. | |
preferredItemWidth / itemWidth | Dp | Target width of the large item. | |
itemSpacing | Dp | 0.dp | Gap between items. |
contentPadding | PaddingValues | PaddingValues(0.dp) | Padding around the carousel content. |
content | @Composable CarouselItemScope.(Int) -> Unit | Item content. Use Modifier.maskClip(shape). |
Guidelines
Do:
- Use for browsing media or categories.
- Show a title on each item.
Don't:
- Do not use a carousel for content that must all be seen.
- Do not autoplay.
Accessibility
- Items that are not fully visible are still part of the accessibility tree. Keep descriptions short.
- Provide another way to reach all items, such as a list view, for users who cannot swipe.
- Keyboard users scroll with the arrow keys once the carousel has focus.