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

```kotlin
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

```kotlin
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.

## Related components

- [Card](https://m3e.ljzapps.app/docs/components/card.md)
- [List](https://m3e.ljzapps.app/docs/components/list.md)