Bloom Logo

Carousel

A touch-enabled, responsive slider component for cycling through images, cards, or custom content with support for autoplay, vertical orientation, and pagination dots with navigation controls.

importimport { Carousel } from "@/components/ui/carousel/carousel";
$npx @bloomui-react/cli add carousel
carousel.tsx
"use client";

import { Icon } from "@iconify/react";
import Autoplay from "embla-carousel-autoplay";
import useEmblaCarousel, {
  type UseEmblaCarouselType,
} from "embla-carousel-react";
import * as React from "react";
import { Button } from "@/components/ui/button/button";
import { cn } from "@/lib/utils";

type CarouselApi = UseEmblaCarouselType[1];
type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
type CarouselOptions = UseCarouselParameters[0];
type CarouselPlugin = UseCarouselParameters[1];

type CarouselProps = {
  opts?: CarouselOptions;
  plugins?: CarouselPlugin;
  orientation?: "horizontal" | "vertical";
  setApi?: (api: CarouselApi) => void;
  autoplay?: boolean;
  autoplayDelay?: number;
  pauseOnHover?: boolean;
  dragFree?: boolean;
  swipeThreshold?: number;
  loop?: boolean;
};

type CarouselContextProps = {
  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
  api: ReturnType<typeof useEmblaCarousel>[1];
  scrollPrev: () => void;
  scrollNext: () => void;
  canScrollPrev: boolean;
  canScrollNext: boolean;
  selectedIndex: number;
  scrollSnaps: number[];
  scrollTo: (index: number) => void;
} & CarouselProps;

const CarouselContext = React.createContext<CarouselContextProps | null>(null);

function useCarousel() {
  const context = React.useContext(CarouselContext);
  if (!context) {
    throw new Error("useCarousel must be used within a <Carousel />");
  }
  return context;
}

const Carousel = React.forwardRef<
  HTMLDivElement,
  React.HTMLAttributes<HTMLDivElement> & CarouselProps
>(
  (
    {
      orientation = "horizontal",
      opts,
      setApi,
      plugins = [],
      autoplay = false,
      autoplayDelay = 3000,
      pauseOnHover = true,
      dragFree = false,
      swipeThreshold = 10,
      loop = false,
      className,
      children,
      ...props
    },
    ref,
  ) => {
    const activePlugins = React.useMemo(() => {
      const list = [...(Array.isArray(plugins) ? plugins : [plugins])];
      if (autoplay) {
        list.push(
          Autoplay({
            delay: autoplayDelay,
            stopOnInteraction: false,
            stopOnMouseEnter: pauseOnHover,
          }),
        );
      }
      return list;
    }, [plugins, autoplay, autoplayDelay, pauseOnHover]);

    const [carouselRef, api] = useEmblaCarousel(
      {
        loop,
        ...opts,
        axis: orientation === "horizontal" ? "x" : "y",
        dragFree,
        dragThreshold: swipeThreshold,
      },
      activePlugins,
    );

    const [canScrollPrev, setCanScrollPrev] = React.useState(false);
    const [canScrollNext, setCanScrollNext] = React.useState(false);
    const [selectedIndex, setSelectedIndex] = React.useState(0);
    const [scrollSnaps, setScrollSnaps] = React.useState<number[]>([]);

    const onSelect = React.useCallback((api: CarouselApi) => {
      if (!api) return;
      setSelectedIndex(api.selectedScrollSnap());
      setCanScrollPrev(api.canScrollPrev());
      setCanScrollNext(api.canScrollNext());
    }, []);

    const scrollTo = React.useCallback(
      (index: number) => {
        api?.scrollTo(index);
      },
      [api],
    );

    const scrollPrev = React.useCallback(() => {
      api?.scrollPrev();
    }, [api]);

    const scrollNext = React.useCallback(() => {
      api?.scrollNext();
    }, [api]);

    React.useEffect(() => {
      if (!api) return;
      setScrollSnaps(api.scrollSnapList());
      onSelect(api);
      api.on("reInit", onSelect);
      api.on("select", onSelect);
      if (setApi) setApi(api);

      return () => {
        api.off("select", onSelect);
      };
    }, [api, onSelect, setApi]);

    return (
      <CarouselContext.Provider
        value={{
          carouselRef,
          api,
          opts,
          orientation:
            orientation || (opts?.axis === "y" ? "vertical" : "horizontal"),
          scrollPrev,
          scrollNext,
          canScrollPrev,
          canScrollNext,
          selectedIndex,
          scrollSnaps,
          scrollTo,
          autoplay,
          autoplayDelay,
          pauseOnHover,
          dragFree,
          swipeThreshold,
          loop,
        }}
      >
        <div
          ref={ref}
          role="region"
          aria-roledescription="carousel"
          className={cn("relative w-full", className)}
          {...props}
        >
          {children}
        </div>
      </CarouselContext.Provider>
    );
  },
);
Carousel.displayName = "Carousel";

const CarouselContent = React.forwardRef<
  HTMLDivElement,
  React.HTMLAttributes<HTMLDivElement>
>(({ className, ...props }, ref) => {
  const { carouselRef, orientation } = useCarousel();

  return (
    <div
      ref={carouselRef}
      className="overflow-hidden size-full cursor-grab active:cursor-grabbing"
    >
      <div
        ref={ref}
        className={cn(
          "flex",
          orientation === "horizontal" ? "-ml-4" : "-mt-4 flex-col",
          className,
        )}
        {...props}
      />
    </div>
  );
});
CarouselContent.displayName = "CarouselContent";

const CarouselItem = React.forwardRef<
  HTMLDivElement,
  React.HTMLAttributes<HTMLDivElement>
>(({ className, ...props }, ref) => {
  const { orientation } = useCarousel();

  return (
    <div
      ref={ref}
      role="group"
      aria-roledescription="slide"
      className={cn(
        "min-w-0 shrink-0 grow-0 basis-full",
        orientation === "horizontal" ? "pl-4" : "pt-4",
        className,
      )}
      {...props}
    />
  );
});
CarouselItem.displayName = "CarouselItem";

const CarouselPrevious = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<typeof Button>
>(({ className, variant = "bordered", size = "sm", ...props }, ref) => {
  const { scrollPrev, canScrollPrev } = useCarousel();

  return (
    <Button
      ref={ref}
      variant={variant}
      size={size}
      isIconOnly
      isDisabled={!canScrollPrev}
      onClick={scrollPrev}
      ariaLabel="Previous slide"
      className={cn(
        "rounded-full bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 text-zinc-900 dark:text-zinc-100 shadow-xs hover:bg-zinc-100 dark:hover:bg-zinc-800 hover:scale-105 active:scale-95 transition-all duration-200",
        className,
      )}
      {...props}
    >
      <Icon icon="hugeicons:arrow-left-01" className="size-4" />
    </Button>
  );
});
CarouselPrevious.displayName = "CarouselPrevious";

const CarouselNext = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<typeof Button>
>(({ className, variant = "bordered", size = "sm", ...props }, ref) => {
  const { scrollNext, canScrollNext } = useCarousel();

  return (
    <Button
      ref={ref}
      variant={variant}
      size={size}
      isIconOnly
      isDisabled={!canScrollNext}
      onClick={scrollNext}
      ariaLabel="Next slide"
      className={cn(
        "rounded-full bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 text-zinc-900 dark:text-zinc-100 shadow-xs hover:bg-zinc-100 dark:hover:bg-zinc-800 hover:scale-105 active:scale-95 transition-all duration-200",
        className,
      )}
      {...props}
    >
      <Icon icon="hugeicons:arrow-right-01" className="size-4" />
    </Button>
  );
});
CarouselNext.displayName = "CarouselNext";

const CarouselDots = React.forwardRef<
  HTMLDivElement,
  React.HTMLAttributes<HTMLDivElement>
>(({ className, ...props }, ref) => {
  const { scrollSnaps, selectedIndex, scrollTo } = useCarousel();

  if (!scrollSnaps.length) return null;

  return (
    <div
      ref={ref}
      className={cn("flex items-center justify-center gap-1.5", className)}
      {...props}
    >
      {scrollSnaps.map((_, index) => (
        <button
          key={index}
          onClick={() => scrollTo(index)}
          aria-label={`Go to slide ${index + 1}`}
          className={cn(
            "h-2 rounded-full transition-all duration-300 cursor-pointer",
            index === selectedIndex
              ? "bg-sky-500 w-6"
              : "bg-zinc-300 dark:bg-zinc-700 hover:bg-zinc-400 dark:hover:bg-zinc-600 w-2",
          )}
        />
      ))}
    </div>
  );
});
CarouselDots.displayName = "CarouselDots";

export interface CarouselThumbsProps
  extends React.HTMLAttributes<HTMLDivElement> {
  images?: string[];
}

const CarouselThumbs = React.forwardRef<HTMLDivElement, CarouselThumbsProps>(
  ({ className, images = [], ...props }, ref) => {
    const { selectedIndex, scrollTo, scrollSnaps } = useCarousel();

    if (!images.length && !scrollSnaps.length) return null;

    return (
      <div
        ref={ref}
        className={cn(
          "flex items-center justify-center gap-2 overflow-x-auto py-2",
          className,
        )}
        {...props}
      >
        {images.map((src, index) => (
          <button
            key={index}
            onClick={() => scrollTo(index)}
            className={cn(
              "relative size-14 shrink-0 overflow-hidden rounded-lg border-2 transition-all duration-200 focus:outline-none cursor-pointer",
              index === selectedIndex
                ? "border-sky-500 scale-105 shadow-sm"
                : "border-transparent opacity-60 hover:opacity-100",
            )}
          >
            <img
              src={src}
              alt={`Thumbnail ${index + 1}`}
              className="size-full object-cover"
            />
          </button>
        ))}
      </div>
    );
  },
);
CarouselThumbs.displayName = "CarouselThumbs";

export {
  Carousel,
  type CarouselApi,
  CarouselContent,
  CarouselDots,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
  CarouselThumbs,
};

Default

Standard image slider with navigation buttons placed alongside pagination dots underneath.

Slide 1
Slide 2
Slide 3

Header Controls

Place navigation buttons inside a section header alongside the title while keeping dots underneath.

w-full: anyflex: anyitems-center: anyjustify-between: anymb-4: anyfont-semibold: anytext-lg: anygap-2: anyml-3: anykey: anyindex: anypl-3: anybasis-full: anysm: anybasis-1: anymd: anyp-5: anyrounded-2xl: anyborder: anyborder-zinc-200: anydark: anyborder-zinc-800: anybg-white: anybg-zinc-900: anyh-40: anymt-4: any

Featured Collections

Handpicked items for your workflow

Popular
Analytics Dashboard

Real-time metrics and visitor insights

Secure
Authentication

OAuth2 and multi-factor security

Fast
Database Sync

Automated distributed state syncing

Scalable
Cloud Storage

Encrypted asset storage & CDN delivery

Thumbnail Navigation

Render a dedicated image thumbnail navigation bar using CarouselThumbs underneath the main slider.

w-full: anykey: anyindex: anyoverflow-hidden: anyrounded-2xl: anyborder: anyborder-zinc-200: anydark: anyborder-zinc-800: anyaspect-video: anysrc: anyalt: anysize-full: anyobject-cover: anyimages: anymt-3: any
Slide 1
Slide 2
Slide 3

Free Drag & Swipe Sensitivity

Use dragFree for continuous physics momentum scrolling and swipeThreshold to customize gesture sensitivity on touch devices.

dragFree: booleanswipeThreshold: number
Analytics Dashboard

Real-time metrics and visitor insights

Authentication

OAuth2 and multi-factor security

Database Sync

Automated distributed state syncing

Cloud Storage

Encrypted asset storage & CDN delivery

Infinite Loop

Set loop to true to enable infinite cycling through slides. Transitioning past the last item returns to the first item with a continuous forward motion.

loop: boolean
Slide 1
Slide 2
Slide 3
API Reference