Carousel

Import

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
} from "@timelycare/helix-ui"

Props

interface CarouselProps {
  orientation?: "horizontal" | "vertical"
  opts?: {
    align?: "start" | "center" | "end"
    loop?: boolean
    dragFree?: boolean
    // Additional Embla options
  }
  plugins?: EmblaPluginType[]
  setApi?: (api: EmblaCarouselType) => void
  className?: string
  children: React.ReactNode
}

interface CarouselItemProps {
  className?: string
  children: React.ReactNode
}

Variants

Choosing a Variant

• Horizontal: Most use cases - product showcases, image galleries
• Vertical: Constrained vertical spaces, testimonial rotators

Styling

Arrow Buttons

Arrow Icon

CarouselItem (Card Container)

Layout

Description Text

Sizes

Control items per view with basis-* classes on CarouselItem:

States

Arrow Button States

Icons

Size: size-4 (16×16px)

Common Patterns

Basic Carousel

<Carousel className="w-full max-w-xs">
  <CarouselContent>
    {Array.from({ length: 5 }).map((_, index) => (
      <CarouselItem key={index}>
        <Card className="border border-border rounded-xl shadow-xs overflow-hidden">
          <CardContent className="flex aspect-square items-center justify-center p-6">
            <span className="text-4xl font-semibold">{index + 1}</span>
          </CardContent>
        </Card>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Multiple Items Per View

<Carousel opts={{ align: "start" }} className="w-full max-w-sm">
  <CarouselContent className="gap-4">
    {items.map((item, index) => (
      <CarouselItem key={index} className="p-1 md:basis-1/2 lg:basis-1/3">
        <Card className="border border-border rounded-xl shadow-xs overflow-hidden">
          <CardContent className="flex aspect-square items-center justify-center p-6">
            {item.content}
          </CardContent>
        </Card>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Vertical Carousel

<Carousel orientation="vertical" className="w-full max-w-xs">
  <CarouselContent className="-mt-1 h-[200px]">
    {items.map((item, index) => (
      <CarouselItem key={index} className="pt-1 md:basis-1/2">
        <Card className="border border-border rounded-xl shadow-xs overflow-hidden">
          <CardContent className="flex items-center justify-center p-6">
            {item.content}
          </CardContent>
        </Card>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

With Slide Counter

function CarouselWithCounter() {
  const [api, setApi] = useState<EmblaCarouselType>()
  const [current, setCurrent] = useState(0)
  const [count, setCount] = useState(0)

  useEffect(() => {
    if (!api) return
    setCount(api.scrollSnapList().length)
    setCurrent(api.selectedScrollSnap() + 1)
    api.on("select", () => setCurrent(api.selectedScrollSnap() + 1))
  }, [api])

  return (
    <Carousel setApi={setApi}>
      <CarouselContent>
        {/* items */}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
      <div className="py-2 text-center text-sm text-muted-foreground">
        Slide {current} of {count}
      </div>
    </Carousel>
  )
}

With Images

<Carousel className="w-full max-w-md">
  <CarouselContent>
    {images.map((image, index) => (
      <CarouselItem key={index}>
        <Card className="border border-border rounded-xl shadow-xs overflow-hidden">
          <AspectRatio ratio={1}>
            <img
              src={image.src}
              alt={image.alt}
              className="absolute inset-0 size-full object-cover"
            />
          </AspectRatio>
        </Card>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Accessibility

• Arrow buttons have accessible labels ("Previous slide" / "Next slide")
• Disabled buttons at carousel bounds
• Keyboard navigation via arrow keys
• Consider pause-on-hover for auto-play carousels

Gotchas

See Also

• Related Components: Card (card carousel), Aspect Ratio (slide sizing)
• Tokens: Colors — Theme-aware color tokens

Last updated: February 9, 2026