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.

2 variantsThemed defaults

import dev.formaui.components.carousel.FormaCarousel

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

KOTLIN

12345678910111213val 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.

ParameterTypeDefaultDescription

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.

PreviousCard Next Checkbox