Carousel
---import { Card, CardContent } from "@/components/starwind/card";import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,} from "@/components/starwind/carousel";---
<Carousel opts={{ align: "start" }} class="mx-auto w-full max-w-xs"> <CarouselContent> { Array.from({ length: 5 }).map((_, index) => ( <CarouselItem> <div class="p-1"> <Card> <CardContent class="flex aspect-square items-center justify-center p-6"> <span class="text-4xl font-semibold">{index + 1}</span> </CardContent> </Card> </div> </CarouselItem> )) } </CarouselContent> <CarouselPrevious /> <CarouselNext /></Carousel>import { Card, CardContent } from "@/components/starwind/card";import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,} from "@/components/starwind/carousel";
export function Example() { return ( <Carousel opts={{ align: "start" }} className="mx-auto w-full max-w-xs"> <CarouselContent> { Array.from({ length: 5 }).map((_, index) => ( <CarouselItem key={index}> <div className="p-1"> <Card> <CardContent className="flex aspect-square items-center justify-center p-6"> <span className="text-4xl font-semibold">{index + 1}</span> </CardContent> </Card> </div> </CarouselItem> )) } </CarouselContent> <CarouselPrevious /> <CarouselNext /> </Carousel> );}Installation
pnpx starwind@latest add carouselnpx starwind@latest add carouselyarn dlx starwind@latest add carouselFramework Availability
Astro Available React AvailableCarousel is available for Astro and React.
Usage
General Notes
The Carousel component is built on top of Embla Carousel and provides a responsive, touch-enabled carousel with smooth animations. It supports both horizontal and vertical orientations, multiple items per view, and various configuration options.
The essential components are Carousel, CarouselContent, and CarouselItem. The CarouselPrevious and CarouselNext components provide navigation controls.
Multiple Items
Show multiple items at once by using responsive basis classes on carousel items.
---import { Card, CardContent } from "@/components/starwind/card";import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,} from "@/components/starwind/carousel";---
<Carousel opts={{ align: "start" }} class="mx-auto w-full max-w-sm"> <CarouselContent> { Array.from({ length: 5 }).map((_, index) => ( <CarouselItem class="md:basis-1/2 lg:basis-1/3"> <div class="p-1"> <Card> <CardContent class="flex aspect-square items-center justify-center p-6"> <span class="text-2xl font-semibold">{index + 1}</span> </CardContent> </Card> </div> </CarouselItem> )) } </CarouselContent> <CarouselPrevious /> <CarouselNext /></Carousel>Vertical Carousel
Carousels can be oriented vertically by setting the orientation prop.
---import { Card, CardContent } from "@/components/starwind/card";import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,} from "@/components/starwind/carousel";---
<Carousel opts={{ align: "start" }} orientation="vertical" class="my-10 w-full max-w-xs"> <CarouselContent class="h-[200px] min-w-[140px]"> { Array.from({ length: 5 }).map((_, index) => ( <CarouselItem class="aspect-square pt-1 md:basis-3/4"> <div class="h-full p-1"> <Card class="h-full"> <CardContent class="flex h-full items-center justify-center p-6"> <span class="text-3xl font-semibold">{index + 1}</span> </CardContent> </Card> </div> </CarouselItem> )) } </CarouselContent> <CarouselPrevious /> <CarouselNext /></Carousel>Looping Carousel
Enable infinite looping with the loop option.
---import { Card, CardContent } from "@/components/starwind/card";import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,} from "@/components/starwind/carousel";---
<Carousel opts={{ align: "start", loop: true }} class="mx-auto w-full max-w-xs"> <CarouselContent> <CarouselItem> <div class="p-1"> <Card class="bg-gradient-to-br from-blue-500 to-purple-600 text-white"> <CardContent class="flex aspect-square items-center justify-center p-6"> <span class="text-4xl font-semibold">∞</span> </CardContent> </Card> </div> </CarouselItem> <CarouselItem> <div class="p-1"> <Card class="bg-gradient-to-br from-green-500 to-blue-600 text-white"> <CardContent class="flex aspect-square items-center justify-center p-6"> <span class="text-4xl font-semibold">Loop</span> </CardContent> </Card> </div> </CarouselItem> <CarouselItem> <div class="p-1"> <Card class="bg-gradient-to-br from-pink-500 to-red-600 text-white"> <CardContent class="flex aspect-square items-center justify-center p-6"> <span class="text-4xl font-semibold">∞</span> </CardContent> </Card> </div> </CarouselItem> </CarouselContent> <CarouselPrevious /> <CarouselNext /></Carousel>Plugins
Extend carousel functionality with Embla Carousel plugins. First install the plugin package, then manually initialize the Runtime primitive with createCarousel.
Info
You need to set autoInit={false} on the Carousel component, so that you can manually initialize it with your plugins and any additional options.
# Install the autoplay pluginnpm install embla-carousel-autoplay---import { Card, CardContent } from "@/components/starwind/card";import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,} from "@/components/starwind/carousel";---
<Carousel id="carousel-autoplay" autoInit={false} opts={{ align: "start" }} class="mx-auto w-full max-w-xs"> <CarouselContent> { Array.from({ length: 5 }).map((_, index) => ( <CarouselItem> <div class="p-1"> <Card> <CardContent class="flex aspect-square items-center justify-center p-6"> <span class="text-4xl font-semibold">{index + 1}</span> </CardContent> </Card> </div> </CarouselItem> )) } </CarouselContent> <CarouselPrevious /> <CarouselNext /></Carousel>
<script> import Autoplay from "embla-carousel-autoplay";
import { createCarousel } from "@starwind-ui/astro/carousel";
function initAutoplayCarousel() { const carouselElement = document.getElementById("carousel-autoplay"); if (!carouselElement) return; createCarousel(carouselElement, { opts: { align: "start" }, plugins: [ Autoplay({ delay: 2000, }), ], }); }
initAutoplayCarousel();
document.addEventListener("astro:after-swap", initAutoplayCarousel); document.addEventListener("starwind:init", initAutoplayCarousel);</script>Runtime example adjustment
Plugin carousels disable styled auto-initialization and call createCarousel from @starwind-ui/astro/carousel, including reinitialization hooks for Astro navigation and dynamically added content.
API Reference
Styled Component API
These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.
Carousel
Inherits div attributes.
Contains the following additional props:
autoInit boolean —
- Description
- Controls whether Runtime behavior initializes automatically.
- Classification
- Primitive override
- Primitive prop
- carousel.Root.autoInit
opts import("@starwind-ui/runtime").CarouselOptions["opts"] —
- Description
- Provides options to the underlying carousel engine.
- Classification
- Primitive override
- Primitive prop
- carousel.Root.opts
Carousel Previous
Inherits button attributes.
Contains the following additional props:
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "icon"
- Description
- Selects the component's visual size.
- Classification
- Styled variant
variant "default" | "primary" | "secondary" | "outline" | "ghost" | "info" | "success" | "warning" | "error" "outline"
- Description
- Selects the component's visual variant.
- Classification
- Styled variant
Carousel Next
Inherits button attributes.
Contains the following additional props:
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "icon"
- Description
- Selects the component's visual size.
- Classification
- Styled variant
variant "default" | "primary" | "secondary" | "outline" | "ghost" | "info" | "success" | "warning" | "error" "outline"
- Description
- Selects the component's visual variant.
- Classification
- Styled variant
Primitive And Runtime API
Use these references when you need the lower-level behavior APIs behind Carousel.
Primitive API
Runtime API
- Carousel primitive
createCarouselfrom@starwind-ui/runtime/carousel
Changelog
v2.0.0
- Rebuilt Carousel on Starwind Runtime for navigation, orientation, looping, and plugin lifecycle.
- See the Carousel Primitive for the underlying unstyled anatomy and behavior API.