Carousel

The Carousel component allows you to create interactive slideshows for cycling through elements like images, videos, or cards with intuitive navigation controls and smooth transitions.

Installation

Before using the Carousel component, make sure you have the required dependency installed:

npm install embla-carousel-svelte

Usage

<script>
  import { 
    Carousel,
    CarouselContent,
    CarouselItem,
    CarouselPrevious,
    CarouselNext
  } from "$lib/components/ui/carousel";
</script>

<Carousel>
  <CarouselContent>
    <CarouselItem>Item 1</CarouselItem>
    <CarouselItem>Item 2</CarouselItem>
    <CarouselItem>Item 3</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Examples

Basic Carousel

Here’s a basic example of a carousel with navigation buttons:

<Carousel className="w-full max-w-xs">
  <CarouselContent>
    <CarouselItem className="pl-1">
      <div className="p-1">
        <div className="flex aspect-square items-center justify-center rounded-md bg-primary p-6">
          <span className="text-3xl font-semibold text-primary-foreground">1</span>
        </div>
      </div>
    </CarouselItem>
    <CarouselItem className="pl-1">
      <div className="p-1">
        <div className="flex aspect-square items-center justify-center rounded-md bg-primary p-6">
          <span className="text-3xl font-semibold text-primary-foreground">2</span>
        </div>
      </div>
    </CarouselItem>
    <CarouselItem className="pl-1">
      <div className="p-1">
        <div className="flex aspect-square items-center justify-center rounded-md bg-primary p-6">
          <span className="text-3xl font-semibold text-primary-foreground">3</span>
        </div>
      </div>
    </CarouselItem>
  </CarouselContent>
  <div className="flex justify-end gap-1 py-2">
    <CarouselPrevious className="static translate-y-0 -translate-x-0" />
    <CarouselNext className="static translate-y-0 -translate-x-0" />
  </div>
</Carousel>

Multiple Items

A carousel showing multiple items per slide:

<Carousel className="w-full max-w-sm">
  <CarouselContent className="-ml-2 md:-ml-4">
    {#each Array(5) as _, i}
      <CarouselItem className="pl-2 md:pl-4 basis-1/2">
        <div className="p-1">
          <div className="flex aspect-square items-center justify-center rounded-md bg-secondary p-6">
            <span className="text-3xl font-semibold">{i + 1}</span>
          </div>
        </div>
      </CarouselItem>
    {/each}
  </CarouselContent>
  <div className="flex justify-end gap-1 py-2">
    <CarouselPrevious className="static translate-y-0 -translate-x-0" />
    <CarouselNext className="static translate-y-0 -translate-x-0" />
  </div>
</Carousel>

Film Cards Carousel

A carousel designed for displaying film cards:

<Carousel className="w-full max-w-md">
  <CarouselContent>
    <CarouselItem>
      <div className="p-1">
        <div className="rounded-lg border shadow-sm overflow-hidden">
          <div className="aspect-video bg-muted relative">
            <div className="absolute inset-0 flex items-center justify-center bg-black/40 text-white font-medium">
              Preview Image
            </div>
          </div>
          <div className="p-4">
            <h3 className="font-medium text-lg">The Silent Echo</h3>
            <p className="text-sm text-muted-foreground">Director: Alex Rivera</p>
            <div className="flex items-center gap-2 mt-2">
              <Badge variant="secondary">Drama</Badge>
              <Badge variant="outline">2023</Badge>
            </div>
          </div>
        </div>
      </div>
    </CarouselItem>
    <!-- More CarouselItems... -->
  </CarouselContent>
  <div className="flex justify-center gap-2 py-2 mt-4">
    <CarouselPrevious className="static translate-y-0 -translate-x-0" />
    <CarouselNext className="static translate-y-0 -translate-x-0" />
  </div>
</Carousel>

Vertical Orientation

A carousel with vertical orientation:

<Carousel orientation="vertical" className="w-full max-w-xs h-[300px]">
  <CarouselContent className="h-full">
    <CarouselItem className="pt-1 h-full">
      <div className="p-1 h-full">
        <div className="flex items-center justify-center rounded-md bg-primary h-full p-6">
          <span className="text-3xl font-semibold text-primary-foreground">1</span>
        </div>
      </div>
    </CarouselItem>
    <!-- More Items... -->
  </CarouselContent>
  <div className="flex flex-col absolute -right-12 top-1/2 -translate-y-1/2 gap-1">
    <CarouselPrevious className="static translate-y-0 -translate-x-0 rotate-90" />
    <CarouselNext className="static translate-y-0 -translate-x-0 rotate-90" />
  </div>
</Carousel>

API Reference

Carousel Components

Component	Description
Carousel	The root container for the carousel.
CarouselContent	The container for carousel items.
CarouselItem	The individual carousel item.
CarouselPrevious	The previous button for the carousel.
CarouselNext	The next button for the carousel.

Carousel Properties

Property	Type	Default	Description
orientation	"horizontal" \| "vertical"	"horizontal"	The orientation of the carousel.
opts	CarouselOptions	{}	Options for the Embla Carousel.
plugins	CarouselPlugins	[]	Plugins for the Embla Carousel.
setApi	(api: CarouselAPI \| undefined) => void	() => {}	Function to set the carousel API.
class	string	undefined	Additional CSS classes for the carousel.

CarouselContent Properties

Property	Type	Default	Description
class	string	undefined	Additional CSS classes for the content container.

CarouselItem Properties

Property	Type	Default	Description
class	string	undefined	Additional CSS classes for the item.

CarouselPrevious Properties

Property	Type	Default	Description
variant	ButtonVariant	"outline"	The variant of the button.
size	ButtonSize	"icon"	The size of the button.
class	string	undefined	Additional CSS classes for the button.

CarouselNext Properties

Property	Type	Default	Description
variant	ButtonVariant	"outline"	The variant of the button.
size	ButtonSize	"icon"	The size of the button.
class	string	undefined	Additional CSS classes for the button.

Carousel Options

The opts property accepts all options from the Embla Carousel library. Here are some of the most commonly used options:

Option	Type	Default	Description
loop	boolean	false	Whether the carousel should loop.
align	"start" \| "center" \| "end"	"center"	The alignment of the slide in the carousel.
dragFree	boolean	false	Whether the carousel should be draggable freely.
containScroll	boolean \| "trimSnaps"	false	Whether the carousel should contain the scroll.
slidesToScroll	number	1	The number of slides to scroll at a time.

For a full list of options, refer to the Embla Carousel documentation.

Implementation Details

The Carousel component is built on top of the Embla Carousel library, providing a responsive and customizable carousel experience. The implementation uses Svelte’s context API to manage the carousel state and provide access to navigation methods.

<!-- Carousel implementation -->
<div class={cn("relative", className)} role="region" aria-roledescription="carousel">
  <slot />
</div>

<!-- CarouselContent implementation -->
<div class="overflow-hidden" use:emblaCarouselSvelte={{ options, plugins }} on:emblaInit>
  <div class={cn("flex", orientation === "horizontal" ? "-ml-4" : "-mt-4 flex-col")}>
    <slot />
  </div>
</div>

<!-- CarouselItem implementation -->
<div class={cn("min-w-0 shrink-0 grow-0 basis-full", orientation === "horizontal" ? "pl-4" : "pt-4")}>
  <slot />
</div>

The components are built with accessibility in mind, using proper ARIA attributes and keyboard navigation support.