Carousel
A swipeable pager-based carousel with horizontal and vertical orientations, auto-scroll, dot indicators, fixed-size pages, and optional external state control.
Carousel wraps Compose Foundation's HorizontalPager / VerticalPager with snapping behavior, an animated dot indicator, and optional auto-scroll. Each page receives a zero-based position index via the content lambda. Pass an external PagerState to drive the carousel programmatically.
Basic usage
Auto scroll
Set autoScroll = true to advance pages automatically. Use autoScrollDelayMillis to control the pause between transitions. Auto-scroll pauses while the user is dragging.
Fixed-width pages
Use pageSize = PageSize.Fixed(...) to show partial adjacent pages and hint at horizontal scrollability. Pair with itemSpacing for the gap between pages.
API reference
Carousel
| Parameter | Type | Default | Description |
|---|---|---|---|
containerModifier | Modifier | Modifier | Applied to the outer Column that wraps the pager and indicator. |
modifier | Modifier | Modifier | Applied to the pager itself. |
state | PagerState? | null | External pager state. An internal state is created when null. |
autoScroll | Boolean | false | When true, advances pages automatically after autoScrollDelayMillis. Pauses during drag. |
autoScrollDelayMillis | Long | 3000 | Milliseconds between auto-scroll advances. |
orientation | CarouselOrientation | CarouselOrientation.Horizontal | Scroll axis. |
componentSpacing | Dp | 8.dp | Vertical gap between the pager and the indicator row. |
contentPadding | PaddingValues | PaddingValues(12.dp, 0.dp) | Padding applied inside the pager viewport, revealing adjacent pages. |
showIndicator | Boolean | false | Whether to render the dot indicator below the pager. |
indicatorStyle | IndicatorStyle | CarouselDefaults.carouselIndicator() | Visual style of the dot indicator. |
itemSpacing | Dp | 8.dp | Gap between individual pages. |
itemCount | Int | — | Total number of pages. |
pageSize | PageSize | PageSize.Fill | Size strategy for each page. Use PageSize.Fixed(dp) for partial-page peek. |
onItemChanged | ((Int) -> Unit)? | null | Callback invoked with the new page index whenever the current page changes. |
content | @Composable PagerScope.(position: Int) -> Unit | — | Content for each page, keyed by zero-based position. |
CarouselOrientation
| Value | Description |
|---|---|
Horizontal | Pages scroll left and right (default). |
Vertical | Pages scroll up and down. |
IndicatorStyle
| Field | Type | Description |
|---|---|---|
activeColor | Color | Fill color of the active dot. |
inactiveColor | Color | Fill color of inactive dots. |
activeSize | Dp | Diameter of the active dot. |
inactiveSize | Dp | Diameter of inactive dots. |
shape | Shape | Shape of each dot. Defaults to CircleShape. |
spacing | Dp | Padding around each dot. |
CarouselDefaults
| Member | Description |
|---|---|
carouselIndicator() | Returns an IndicatorStyle using foreground (active) and mutedForeground (inactive) with 12 dp / 8 dp sizes and CircleShape. |