Carousel

A carousel component for cycling through elements, built on top of the powerful and lightweight Embla Carousel library. It provides a flexible and accessible way to display a series of items, with support for various options like looping, alignment, and orientation.

Under the Hood

The RzCarousel component suite uses an Alpine.js component (x-data="rzCarousel") to manage its state and interactivity. This Alpine component acts as a bridge to the Embla Carousel JavaScript library, which is loaded on-demand along with any configured plugins. This means assets are only downloaded by the browser when an RzCarousel is actually used on a page, keeping your initial bundle size small.

Basic Carousel

This example shows a basic carousel with previous and next navigation buttons. The content of each slide is a simple card.

Source

<RzCarousel class="w-full max-w-xs">
    <CarouselContent>
        @for (int i = 1; i <= 5; i++)
        {
            var n = i;
            <CarouselItem>
                <div class="p-1">
                    <RzCard>
                        <CardContent class="flex aspect-square items-center justify-center p-6">
                            <span class="text-4xl font-semibold">@n</span>
                        </CardContent>
                    </RzCard>
                </div>
            </CarouselItem>
        }
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
</RzCarousel>

Sizing

You can adjust the size of the carousel items by applying Tailwind CSS width utilities (like `basis-1/2` or `basis-1/3`) to the `CarouselItem` components.

Source

<RzCarousel class="w-full max-w-sm">
    <CarouselContent>
        @for (int i = 1; i <= 5; i++)
        {
            <CarouselItem class="md:basis-1/2 lg:basis-1/3">
                <!-- Item Content -->
            </CarouselItem>
        }
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
</RzCarousel>

Spacing

Create space between carousel items using a common pattern: apply a negative margin to the `CarouselContent` and a corresponding positive padding to each `CarouselItem`.

Source

<RzCarousel class="w-full max-w-sm">
    <CarouselContent class="-ml-4">
        @for (int i = 1; i <= 5; i++)
        {
            <CarouselItem class="pl-4 md:basis-1/2 lg:basis-1/3">
                <!-- Item Content -->
            </CarouselItem>
        }
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
</RzCarousel>

Vertical Carousel

Set the Axis property to "y" in CarouselOptions to create a vertical carousel. You will also need to adjust the styling of the content container to use a vertical flex layout and have a defined height.

Source

<RzCarousel Options="@(new CarouselOptions { Axis = "y" })" class="w-full max-w-xs">
    <CarouselContent class="flex-col h-60 -mt-4">
        @for (int i = 1; i <= 5; i++)
        {
            <CarouselItem class="pt-4">
                <!-- Item Content -->
            </CarouselItem>
        }
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
</RzCarousel>

Autoplay with Plugins

Extend the carousel's functionality with Embla plugins. This example demonstrates the Autoplay plugin. Simply instantiate the `AutoplayPlugin` class with its options and pass it to the `Plugins` parameter of the `RzCarousel`. RizzyUI will handle loading the necessary JavaScript assets.

Source

<RzCarousel Options="@(new CarouselOptions { Loop = true })"
            Plugins="@(new[] { new AutoplayPlugin(new AutoplayPluginOptions { Delay = 2000, StopOnInteraction = false }) })"
            class="w-full max-w-xs">
</RzCarousel>

Component Parameters

The following tables summarize the parameters for each component in the Carousel suite.

RzCarousel

Property	Type	Default	Description
`ChildContent`	`RenderFragment`	Required	The content of the carousel, including `CarouselContent` and navigation.
`Options`	`CarouselOptions`	`new()`	Configuration options for the Embla Carousel instance.
`Plugins`	`IEnumerable<EmblaPlugin>`	`Empty`	A collection of Embla plugins to initialize with the carousel.
`AriaLabel`	`string?`	Localized "Carousel"	Accessible label for the carousel region.

CarouselOptions

The Options parameter accepts a CarouselOptions object. Below are some of the most common properties. For a full list, refer to the Embla Carousel documentation.

Property	Type	Description
`Align`	`string?`	Aligns slides to "start", "center", or "end".
`Axis`	`string?`	Sets the scroll axis to "x" (horizontal) or "y" (vertical).
`Loop`	`bool?`	Enables infinite looping.
`StartIndex`	`int?`	The zero-based index of the slide to show on initialization.
`DragFree`	`bool?`	Enables "free-scrolling" mode without snapping to slides.

CarouselContent & CarouselItem

These components primarily accept ChildContent and pass through any additional attributes. They have no unique parameters beyond standard HTML attributes.

CarouselPrevious & CarouselNext

Property	Type	Default	Description
`AriaLabel`	`string?`	Localized default	Accessible label for the button.
`AsChild`	`bool`	`false`	Merges behavior into a single child element instead of rendering a button.
`ChildContent`	`RenderFragment?`	`null`	The content of the button. If `null` and `AsChild` is `false`, a default icon is rendered. Used as the child for merging when `AsChild` is `true`.