Skip to content

Extra

Carousel

A FormaUI carousel — a horizontally scrolling, snapping strip of items — one entry point covering both Material 3 horizontal carousel families (multi-browse and uncontained) via a variant enum, with hoisted M3 CarouselState and an indexed item slot.

dev.formaui.components.carousel

MultiBrowseUncontained

Preview

This toggle is site chrome only — the preview has its own light/dark switch inside.

Live preview

Live preview — ~37 MB development build

Usage

val state = rememberCarouselState(itemCount = { photos.size })
FormaCarousel(
    state = state,
    itemWidth = 220.dp,
    modifier = Modifier.height(200.dp),
) { index ->
    Image(
        painter = photos[index].painter,
        contentDescription = photos[index].description,
        modifier = Modifier.fillMaxSize().maskClip(FormaTheme.shapes.lg),
        contentScale = ContentScale.Crop,
    )
}

FormaCarousel

One entry point for both M3 horizontal carousels; a single itemWidth maps to preferredItemWidth (MultiBrowse) or the exact itemWidth (Uncontained), with an opinionated default item spacing and per-variant default fling.

staterequiredTypeCarouselStateDefaultrequiredDescriptionthe hoisted CarouselState; create it with Material 3's rememberCarouselState(itemCount = { ... }).
itemWidthrequiredTypeDpDefaultrequiredDescriptionthe item width — the preferred (flexing) width for FormaCarouselVariant.MultiBrowse, the exact width for FormaCarouselVariant.Uncontained.
modifierTypeModifierDefaultModifierDescriptionthe Modifier applied to the carousel (typically sets its height).
variantTypeFormaCarouselVariantDefaultFormaCarouselVariant.MultiBrowseDescriptionthe layout strategy (defaults to FormaCarouselVariant.MultiBrowse).
itemSpacingTypeDpDefaultFormaCarouselDefaults.itemSpacingDescriptionthe gap between items (defaults to FormaCarouselDefaults.itemSpacing, an opinionated small gap; pass 0.dp for Material 3's flush default).
contentPaddingTypePaddingValuesDefaultPaddingValues(0.dp)Descriptionpadding around the whole content strip (defaults to none).
flingBehaviorTypeTargetedFlingBehavior?DefaultnullDescriptionthe post-scroll fling behavior. When null, the Material 3 default for the variant is used (a single-advance snap for MultiBrowse, a no-snap fling for Uncontained).
userScrollEnabledTypeBooleanDefaulttrueDescriptionwhether the user can scroll the carousel by gesture.
contentrequiredType@Composable CarouselItemScope.(index: Int) -> UnitDefaultrequiredDescriptionthe item slot, invoked per item with its index, in a CarouselItemScope (use its mask modifiers, e.g. Modifier.maskClip, to shape items).

Supporting API

FormaCarouselVariantenum
Layout strategy of a FormaCarousel: MultiBrowse (default; flexing large/medium/small items), Uncontained (every item keeps the exact width).
FormaCarouselDefaultsobject
Defaults for FormaCarousel: itemSpacing (FormaTheme.spacing.xs — a small opinionated gap, vs Material 3's 0.dp).
rememberCarouselStatefunction (Material 3)
The component defines no state type of its own — callers create and own the state via Material 3's rememberCarouselState(initialItem, itemCount).

Accessibility

The carousel is a horizontally scrollable container; supply a meaningful contentDescription on each item's own content (e.g. the Image inside the slot). Material 3 handles the scroll/snap semantics.