Carousel React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Carousel is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Carousel from @/components/ui/carousel.

import { Carousel } from "@/components/ui/carousel"

const photos = ["/demo/apartment.jpg", "/demo/sofa.jpg", "/demo/city.jpg"]

export function ListingPhotos() {
  return (
    <Carousel label="Apartment photos" indicator="counter" indicatorPosition="overlay" thumbnails={photos}>
      {photos.map((src, i) => (
        <img key={src} src={src} alt={`Photo ${i + 1}`} draggable={false} className="aspect-[4/3] w-full object-cover" />
      ))}
    </Carousel>
  )
}

Props

• children
  ReactNode

  The slides. Each child is wrapped in a CarouselSlide (role group, "3 of 8") unless it already is one. Images inside should be draggable={false}.

• slidesPerViewdefault "1"
  number | "auto" | { base?: number; sm?: number; md?: number; lg?: number }

  Slides visible at once. Fractions peek (1.15 shows 15% of the next slide). An object sets it by the carousel's own width (container queries: base, sm from 640px, md from 768px, lg from 1024px), so a rail in a narrow column shows fewer slides and the server layout is already right. "auto" sizes slides by their content width. The playground offers 1, 1.15, 2, 3 and auto.

• peekdefault true
  boolean

  While the carousel is narrower than 640px (a phone), whole-number slidesPerView values show 12% of the next slide (1 becomes 1.12), so it always hints that there is more.

• gapdefault "md"
  "none" | "sm" | "md" | "lg"

  Space between slides: 0 / 8 / 12 / 16px.

• aligndefault "start"
  "start" | "center"

  Where the selected slide sits in the viewport. center suits the scale effect and testimonials.

• orientationdefault "horizontal"
  "horizontal" | "vertical"

  vertical scrolls up and down (tickers, stories); give the viewport a height through classNames.viewport (320px by default).

• loopdefault false
  boolean

  Wraps from the last slide to the first. Embla turns it off by itself when there are too few slides to fill the view.

• dragFreedefault false
  boolean

  Momentum without snapping, for rails of chips or cards.

• wheeldefault true
  boolean

  A two-finger trackpad swipe (or Shift + mouse wheel) along the track moves it one slide per swipe; dragFree tracks follow the swipe.

• arrowsdefault "auto"
  "auto" | "always" | "never"

  auto shows the arrows on fine pointers only (phones swipe) and hides them when there is nothing to scroll; always shows them on touch too.

• arrowPositiondefault "inside"
  "inside" | "outside" | "header"

  inside: round glass buttons over the middle of the viewport. outside: beside the viewport from 1024px up (inside below). header: a pair at the top end, next to the title of a rail.

• indicatordefault "dots"
  "dots" | "bars" | "progress" | "counter" | "none"

  dots: 6px dots, the active one stretched to 18px. bars: story-like segments that autoplay fills. progress: one thin bar tracking the scroll. counter: a "3 / 8" pill.

• indicatorPositiondefault "below"
  "below" | "overlay"

  overlay puts the indicator (and the pause button) inside the bottom of the viewport on a dark gradient, for photo galleries.

• effectdefault "none"
  "none" | "scale" | "parallax"

  scale: slides away from the snap shrink to 0.9 and dim. parallax: media marked data-carousel-parallax shifts against the drag. Both read --slide-progress, written per scroll event (never React state); off under reduced motion.

• sizedefault "md"
  "sm" | "md" | "lg"

  Arrow and indicator sizes: arrows 32 / 40 / 48px, dots 5 / 6 / 8px, thumbnails 48 / 56 / 64px.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  Slide and viewport corners: 0 / 12 / 16 / 24px.

• autoplaydefault false
  boolean

  Advances every interval (our own timer, no plugin). Pauses while hovered, focused, dragged, hidden or off screen, stops at the end without loop, and always shows a pause / play button (WCAG 2.2.2).

• intervaldefault 5000
  number

  Milliseconds per slide while autoplaying.

• pauseOnHoverdefault true
  boolean

  Autoplay waits while a mouse is over the carousel.

• stopOnInteractiondefault false
  boolean

  false: a drag, an arrow or a dot restarts the timer; true: autoplay stops until the play button is pressed.

• labeldefault "Carousel"
  string

  The region's aria-label, read as "Carousel, carousel" by screen readers. Name it after its content.

• title
  ReactNode

  A heading above the viewport; the header arrows sit beside it. It also names the region (aria-labelledby) unless label is set.

• thumbnails
  (string | ReactNode)[]

  A synced strip under the viewport: image urls or nodes, one per slide. The selected one stays in view.

• index
  number

  The selected snap, controlled. Pair with onIndexChange.

• defaultIndexdefault 0
  number

  The snap shown first, uncontrolled. The playground remounts the carousel when it changes.

• onIndexChange
  (index: number) => void

  Fires when the selected snap changes, by drag, arrow, dot, key or autoplay.

• labels
  Partial<CarouselLabels>

  Every string: previous, next, slide(i, n) ("3 of 8"), goTo(i) ("Go to slide 3"), pause, play, carousel and slideRole (the aria-roledescriptions). English by default, DEFAULT_CAROUSEL_LABELS.

• opts
  EmblaOptionsType

  Anything else for embla (slidesToScroll, skipSnaps, duration, containScroll...). Wins over the props above.

• setApi
  (api: CarouselApi) => void

  Receives the embla api once it is ready.

• classNames
  Partial<Record<"header" | "title" | "stage" | "viewport" | "container" | "slide" | "previous" | "next" | "indicator" | "dot" | "counter" | "autoplay" | "thumbnails" | "thumbnail" | "footer" | "overlay", string>>

  Extra classes for the inner parts.

Parts

FAQ

Used in

More React media components