<br />

Try the Compose way  
Jetpack Compose is the recommended UI toolkit for Android. Learn how to add a carousel in Compose.  
[Carousel →](https://developer.android.com/develop/ui/compose/components/carousel)  
![](https://developer.android.com/static/images/android-compose-ui-logo.png)

<br />

[`Carousel`](https://developer.android.com/reference/androidx/constraintlayout/helper/widget/Carousel)is a motion helper object to build custom carousel views that show a list of elements that the user can skim through. Compared to other ways to implement such views, this helper lets you quickly create complex motion and dimension changes for your`Carousel`by taking advantage of[`MotionLayout`](https://developer.android.com/reference/androidx/constraintlayout/motion/widget/MotionLayout).
**Figure 1.** Example of a`Carousel`showing landscape pictures.

The`Carousel`widget supports lists with a start and end as well as circular wrap-around lists.
| **Note:** For a more hands-on approach, see the[CarouselExperiments sample project](https://github.com/androidx/constraintlayout/tree/main/projects/CarouselExperiments)on GitHub.

## How Carousel with MotionLayout works

Suppose you want to build a horizontal`Carousel`view, with the center item enlarged:
![An image showing a carousel wireframe](https://developer.android.com/static/images/training/constraint-layout/carousel-ex1.png)**Figure 2.** Example of an image`Carousel`showing a larger image in the center.

This basic layout contains several views representing the`Carousel`items:
![An image showing a carousel wireframe](https://developer.android.com/static/images/training/constraint-layout/carousel-ex2.png)**Figure 3.**Widget details.

Create a`MotionLayout`with the following three states and give them IDs:

- **previous**
- **start**
- **next**

If the**start** state corresponds to the base layout, in the**previous** state and the**next** state the`Carousel`items are shifted by one to the left and to the right, respectively.

For example, take the five views in figure 3 and assume that in the**start** state, views B, C, and D are visible, and A and E are outside of the screen. Set up the**previous** state so that the positions of A, B, C, and D are where B, C, D, and E were, with the views moving from left to right. In the**next**state, the opposite needs to happen, with B, C, D, and E moving to where A, B, C, and D were, and the views moving from right to left. This is shown in figure 4:
![An image showing a carousel back and forward transition](https://developer.android.com/static/images/training/constraint-layout/carousel-ex3.png)**Figure 4.** `Carousel`swiping transitions.

It's critical that the views end up exactly where the original views start.`Carousel`gives the illusion of an infinite collection of elements by moving the*actual*views back to where they were, but reinitializing them with the new matching content. The following diagram shows this mechanism. Pay attention to the "item #" values):
![An image showing a carousel back and forward transition](https://developer.android.com/static/images/training/constraint-layout/carousel-ex4.png)**Figure 5.** `Carousel`swiping transitions and state reset.

### Transitions

With these three constraint sets defined in your motion scene file, create two transitions---forward and backward---between the**start** and**next** states and the**start** and**previous** states. Add an[`OnSwipe`](https://developer.android.com/training/constraint-layout/motionlayout/ref/onswipe)handler to trigger the transitions in response to a gesture, as shown in the following example:  

        <Transition
            motion:constraintSetStart="@id/start"
            motion:constraintSetEnd="@+id/next"
            motion:duration="1000"
            android:id="@+id/forward">
            <OnSwipe
                motion:dragDirection="dragLeft"
                motion:touchAnchorSide="left" />
        </Transition>

        <Transition
            motion:constraintSetStart="@+id/start"
            motion:constraintSetEnd="@+id/previous"
            android:id="@+id/backward">
            <OnSwipe
                motion:dragDirection="dragRight"
                motion:touchAnchorSide="right" />
        </Transition>

### Add the Carousel

After this basic motion scene is created, add a`Carousel`helper to the layout and reference the views in the same order you implement your previous and next animation.

Set the following attributes for the`Carousel`helper:

- `app:carousel_firstView`: the view that represents the first element of the`Carousel`---in this example, C.
- `app:carousel_previousState`: the`ConstraintSet`ID of the**previous**state.
- `app:carousel_nextState`: the`ConstraintSet`ID of the**next**state.
- `app:carousel_backwardTransition`: the[`Transition`](https://developer.android.com/reference/androidx/constraintlayout/motion/widget/MotionLayout#transition)ID applied between the**start** and**previous**states.
- `app:carousel_forwardTransition`: the`Transition`ID applied between the**start** and**next**states.

For example, you have something like this in your layout XML file:  

        <androidx.constraintlayout.motion.widget.MotionLayout ... >

            <ImageView  android:id="@+id/imageView0" .. />
            <ImageView  android:id="@+id/imageView1" .. />
            <ImageView  android:id="@+id/imageView2" .. />
            <ImageView  android:id="@+id/imageView3" .. />
            <ImageView  android:id="@+id/imageView4" .. />

            <androidx.constraintlayout.helper.widget.Carousel
                android:id="@+id/carousel"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                app:carousel_forwardTransition="@+id/forward"
                app:carousel_backwardTransition="@+id/backward"
                app:carousel_previousState="@+id/previous"
                app:carousel_nextState="@+id/next"
                app:carousel_infinite="true"
                app:carousel_firstView="@+id/imageView2"
                app:constraint_referenced_ids="imageView0,imageView1,imageView2,imageView3,imageView4" />

        </androidx.constraintlayout.motion.widget.MotionLayout>

Set up a`Carousel`adapter in code:  

### Kotlin

```kotlin
carousel.setAdapter(object : Carousel.Adapter {
            override fun count(): Int {
              // Return the number of items in the Carousel.
            }

            override fun populate(view: View, index: Int) {
                // Implement this to populate the view at the given index.
            }

            override fun onNewItem(index: Int) {
                // Called when an item is set.
            }
        })
```

### Java

```java
carousel.setAdapter(new Carousel.Adapter() {
            @Override
            public int count() {
                // Return the number of items in the Carousel.
            }

            @Override
            public void populate(View view, int index) {
                // Populate the view at the given index.
            }

            @Override
            public void onNewItem(int index) {
                 // Called when an item is set.
            }
        });
```

### Additional notes

Depending on the current item "selected" in the`Carousel`, the views representing the items before or after might need to be hidden to correctly account for the`Carousel`**start** and**end** . The`Carousel`helper handles this automatically. By default, it marks those views as`View.INVISIBLE`in these situations, so the overall layout doesn't change.

An alternative mode is available in which the`Carousel`helper instead marks those views as`View.GONE`. You can set this mode using the following property:  

    app:carousel_emptyViewsBehavior="gone"

### Examples

For more examples using the Carousel helper, see the[example projects](https://github.com/androidx/constraintlayout/tree/main/projects/CarouselExperiments)on GitHub.