# HorizontalCenteredHeroCarousel

Common/All

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/HorizontalCenteredHeroCarousel.composable#HorizontalCenteredHeroCarousel(androidx.compose.material3.carousel.CarouselState,androidx.compose.ui.Modifier,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.gestures.TargetedFlingBehavior,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.PaddingValues,kotlin.Function2)( state: https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, preferredItemWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, itemSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/TargetedFlingBehavior, userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, minSmallItemWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, maxSmallItemWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues, content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselItemScope.(itemIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` [Material Design center-aligned hero carousel](https://m3.material.io/components/carousel/specs) | Cmn |

## Functions

### HorizontalCenteredHeroCarousel

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/carousel/Carousel.kt+function:HorizontalCenteredHeroCarousel)

```
@Composable
fun HorizontalCenteredHeroCarousel(
    state: CarouselState,
    modifier: Modifier = Modifier,
    preferredItemWidth: Dp = Dp.Unspecified,
    itemSpacing: Dp = CarouselDefaults.ItemSpacing,
    flingBehavior: TargetedFlingBehavior = CarouselDefaults.singleAdvanceFlingBehavior(state = state),
    userScrollEnabled: Boolean = true,
    minSmallItemWidth: Dp = CarouselDefaults.MinSmallItemSize,
    maxSmallItemWidth: Dp = CarouselDefaults.MaxSmallItemSize,
    contentPadding: PaddingValues = CarouselDefaults.ContentPadding,
    content: @Composable CarouselItemScope.(itemIndex: Int) -> Unit
): Unit
```

[Material Design center-aligned hero carousel](https://m3.material.io/components/carousel/specs)

A horizontal carousel that centers at least one large item between two small items.

Note that this carousel lays out items using the large item size and clips (or masks) items depending on their scroll offset to create items which smoothly expand and collapse between the large and small sizes.

The selected item is centered whenever items sit on both sides of it. At the bounds of the list the arrangement shifts, so the first item aligns to the start of the viewport and the last item aligns to its end:

```kotlin
// Five items, one large item between two small items:
item 1 selected:  [        1        ][2][3]
item 3 selected:  [2][        3        ][4]
item 5 selected:  [3][4][        5        ]
```

Lists holding fewer items than the arrangement needs (three at a minimum) stay start-aligned.

Example of a center-aligned hero carousel:

```kotlin
import androidx.annotation.DrawableRes
import androidx.annotation.StringRes
import androidx.compose.foundation.Image
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.filled.Image
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.carousel.HorizontalCenteredHeroCarousel
import androidx.compose.material3.carousel.rememberCarouselState
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.unit.dp

data class CarouselItem(
    val id: Int,
    @DrawableRes val imageResId: Int,
    @StringRes val contentDescriptionResId: Int,
)

val items =
    listOf(
        CarouselItem(0, R.drawable.carousel_image_1, R.string.carousel_image_1_description),
        CarouselItem(1, R.drawable.carousel_image_2, R.string.carousel_image_2_description),
        CarouselItem(2, R.drawable.carousel_image_3, R.string.carousel_image_3_description),
        CarouselItem(3, R.drawable.carousel_image_4, R.string.carousel_image_4_description),
        CarouselItem(4, R.drawable.carousel_image_5, R.string.carousel_image_5_description),
    )
val state = rememberCarouselState { items.count() }
val animationScope = rememberCoroutineScope()
HorizontalCenteredHeroCarousel(
    state = state,
    modifier = Modifier.fillMaxWidth().height(221.dp).padding(horizontal = 24.dp),
    itemSpacing = 8.dp,
    contentPadding = PaddingValues(horizontal = 16.dp),
) { i ->
    val item = items[i]
    Image(
        modifier =
            Modifier.fillMaxWidth()
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge)
                .clickable(true, "Tap to focus", Role.Image) {
                    animationScope.launch { state.animateScrollToItem(i) }
                },
        painter = painterResource(id = item.imageResId),
        contentDescription = stringResource(item.contentDescriptionResId),
        contentScale = ContentScale.Crop,
    )
}
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselState` | The state object to be used to control the carousel's state |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | A modifier instance to be applied to this carousel container |
| `preferredItemWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = Dp.Unspecified` | The width large items aim for in dp. Carousel picks the arrangement whose large item width lands closest to this value, resizing small items between `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/package-summary#HorizontalCenteredHeroCarousel(androidx.compose.material3.carousel.CarouselState,androidx.compose.ui.Modifier,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.gestures.TargetedFlingBehavior,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.PaddingValues,kotlin.Function2)` and `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/package-summary#HorizontalCenteredHeroCarousel(androidx.compose.material3.carousel.CarouselState,androidx.compose.ui.Modifier,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.gestures.TargetedFlingBehavior,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.PaddingValues,kotlin.Function2)` to fill the rest of the viewport, so the final width can differ. The default `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp#Unspecified()` targets the whole viewport, fitting one large item beside two small items; smaller values fit more large items. Large items always end up wider than the small items beside them, which are never narrower than `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/package-summary#HorizontalCenteredHeroCarousel(androidx.compose.material3.carousel.CarouselState,androidx.compose.ui.Modifier,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.gestures.TargetedFlingBehavior,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.PaddingValues,kotlin.Function2)`, so widths at or below that bound cannot be honored. To target an aspect ratio, use the carousel's cross axis size \* a multiplier (e.g. `220.dp * 2` for a 2:1 ratio). |
| `itemSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = CarouselDefaults.ItemSpacing` | The amount of space used to separate items in the carousel |
| `flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/TargetedFlingBehavior = CarouselDefaults.singleAdvanceFlingBehavior(state = state)` | The `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/TargetedFlingBehavior` to be used for post scroll gestures |
| `userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | whether the scrolling via the user gestures or accessibility actions is allowed. |
| `minSmallItemWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = CarouselDefaults.MinSmallItemSize` | The minimum allowable width of small items in dp |
| `maxSmallItemWidth: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = CarouselDefaults.MaxSmallItemSize` | The maximum allowable width of small items in dp |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues = CarouselDefaults.ContentPadding` | a padding around the whole content. This will add padding for the content after it has been clipped. You can use it to add a padding before the first item or after the last one. Use `https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/package-summary#HorizontalCenteredHeroCarousel(androidx.compose.material3.carousel.CarouselState,androidx.compose.ui.Modifier,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.gestures.TargetedFlingBehavior,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.PaddingValues,kotlin.Function2)` to add spacing between the items. |
| `content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/carousel/CarouselItemScope.(itemIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The carousel's content Composable |