Carousel

A draggable, swipeable slider built on Embla — with autoplay, fade, auto-height, thumbnails, and creative scroll effects.

Usage

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
  CarouselProgress,
} from '@appica/ui-react/carousel'

<Carousel loop>
  <CarouselContent>
    <CarouselSlide>Slide 1</CarouselSlide>
    <CarouselSlide>Slide 2</CarouselSlide>
    <CarouselSlide>Slide 3</CarouselSlide>
  </CarouselContent>
  <CarouselPrev
    render={
      <Button variant="outline" size="icon-md" className="rounded-full">
        <ChevronLeft />
      </Button>
    }
  />
  <CarouselNext
    render={
      <Button variant="outline" size="icon-md" className="rounded-full">
        <ChevronRight />
      </Button>
    }
  />
</Carousel>

Carousel wraps Embla Carousel — a lightweight, dependency-free engine for dragging, snapping, and momentum — and exposes it as a small set of composable parts. Carousel sets up the engine and shares it through context; CarouselContent is the scroll viewport and track; each CarouselSlide is one snap point. Drop in CarouselPrev / CarouselNext for arrows and CarouselPagination or CarouselProgress for position feedback — each reads the engine from context, so they can sit anywhere inside the root.

Every slide is basis-full by default (one per view). Set a smaller basis-* on CarouselSlide to show several at once, and pick where they settle with align. Options that mirror Embla — loop, align, slidesToScroll, dragFree, duration, and more — are flat props on Carousel; the full option object is available through options as an escape hatch.

The arrows (CarouselPrev / CarouselNext) render an unstyled <button> by default so you own their look. Pass a Button (or any element) via render — put structural props like variant/size on that element, and use position to place the arrows inside, outside, or straddling the edge.

Examples

Default

A single slide per view with arrows overlaid inside the frame and a pagination strip below. loop lets it wrap around from the last slide back to the first.

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselDefault() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}

Multiple slides (responsive)

Give each CarouselSlide a fractional basis-* to fit several per view — here basis-1/2 on small screens and basis-1/3 above. slidesToScroll="auto" advances by however many slides are fully visible, and align="start" snaps them to the leading edge.

import { Carousel, CarouselContent, CarouselSlide, CarouselPrev, CarouselNext } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [4, 5, 6, 7, 8, 2]

export default function CarouselMultiple() {
  return (
    <div className="w-full max-w-xl px-15">
      <Carousel align="start" slidesToScroll="auto" loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="sm:basis-1/2 md:basis-1/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>
    </div>
  )
}

Alignment

align controls where slides settle in the viewport — start, center, or end. Combined with a basis smaller than the viewport, center peeks the neighbouring slides on either side.

import { Carousel, CarouselContent, CarouselSlide, CarouselPrev, CarouselNext } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]

export default function CarouselAlignment() {
  return (
    <div className="w-full max-w-xl">
      <Carousel align="center" loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-2/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>
    </div>
  )
}

Vertical

Set orientation="vertical" to drag and snap along the Y axis — same footprint as the horizontal carousel, just scrolling top-to-bottom. The viewport needs a fixed height (here h-100 on CarouselContent); the arrows settle inside at the top and bottom edges automatically, and CarouselPagination takes orientation="vertical" to run its bullets down the side. The same 16px inter-slide gap as the horizontal carousel carries over, so slides don't butt together as you scroll.

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronUp, ChevronDown } from '@appica/icons-react'

const SLIDES = [1, 2, 4, 5]

export default function CarouselVertical() {
  return (
    <div className="w-full">
      <Carousel orientation="vertical" loop className="flex w-full items-center justify-center gap-5">
        <div className="relative w-full max-w-xl">
          <CarouselContent className="h-100">
            {SLIDES.map((n) => (
              <CarouselSlide key={n}>
                <img
                  src={`/carousel/slide-${n}.jpg`}
                  alt={`Slide ${n}`}
                  className="size-full rounded-xl object-cover"
                />
              </CarouselSlide>
            ))}
          </CarouselContent>
          <CarouselPrev
            render={
              <Button variant="outline" size="icon-md" className="rounded-full">
                <ChevronUp />
              </Button>
            }
          />
          <CarouselNext
            render={
              <Button variant="outline" size="icon-md" className="rounded-full">
                <ChevronDown />
              </Button>
            }
          />
        </div>
        <CarouselPagination orientation="vertical" />
      </Carousel>
    </div>
  )
}

Autoplay

Pass autoplay to advance on a timer via Embla's Autoplay plugin. Give it an object to tune the delay, and add resumeAfter extension to restart the timer a set time after the user interacts. When autoplay is running, the active pagination bullet grows into a filling progress pill.

import { Carousel, CarouselContent, CarouselSlide, CarouselPagination } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 5, 4, 7, 6]

export default function CarouselAutoplay() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop autoplay={{ delay: 4000, resumeAfter: 3000 }}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}

Auto Scroll

autoScroll swaps the discrete timer for continuous marquee-style motion via the Auto Scroll plugin — pair it with loop and dragFree for an endless conveyor. Like autoplay, it accepts resumeAfter extension to restart the scroll a set time after the user interacts. autoScroll and autoplay are mutually exclusive. Auto Scroll pauses under prefers-reduced-motion.

import { Carousel, CarouselContent, CarouselSlide } from '@appica/ui-react/carousel'

const SLIDES = [1, 2, 3, 4, 5, 6, 7, 8]

export default function CarouselAutoScroll() {
  return (
    <div className="w-full max-w-xl">
      <Carousel loop dragFree autoScroll={{ speed: 1.5, startDelay: 0, resumeAfter: 3000 }}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/2 sm:basis-1/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}

Fade

fade cross-fades between slides instead of sliding them, using the Fade plugin. It's meant for one slide per view — ideal for a hero or a full-bleed gallery.

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselFade() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop fade>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}

Auto Height

autoHeight animates the viewport to each slide's natural height as you navigate, via the Auto Height plugin — so mixed-length content doesn't clip or leave dead space. Use align="start" so slides measure from the top.

Short

A compact slide.

Medium

This slide carries a couple of sentences, so it stands a little taller than the first. The viewport grows to fit it.

Tall

And this one runs longer still. Auto Height animates the viewport between each slide's natural height as you navigate, so nothing is clipped and there's no empty space below shorter slides. It keeps mixed-length content — quotes, cards, forms — looking tidy inside a single carousel.

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const CARDS = [
  { title: 'Short', body: 'A compact slide.' },
  {
    title: 'Medium',
    body: 'This slide carries a couple of sentences, so it stands a little taller than the first. The viewport grows to fit it.',
  },
  {
    title: 'Tall',
    body: "And this one runs longer still. Auto Height animates the viewport between each slide's natural height as you navigate, so nothing is clipped and there's no empty space below shorter slides. It keeps mixed-length content — quotes, cards, forms — looking tidy inside a single carousel.",
  },
]

export default function CarouselAutoHeight() {
  return (
    <div className="w-full max-w-md">
      <Carousel loop autoHeight align="start">
        <CarouselContent>
          {CARDS.map((card) => (
            <CarouselSlide key={card.title}>
              <div className="border-border-muted bg-background-subtle rounded-xl border p-6">
                <h4 className="text-foreground-intense mb-2 font-semibold">{card.title}</h4>
                <p className="text-sm">{card.body}</p>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex items-center justify-between gap-4">
          <CarouselPrev
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronLeft />
              </Button>
            }
          />
          <CarouselPagination />
          <CarouselNext
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronRight />
              </Button>
            }
          />
        </div>
      </Carousel>
    </div>
  )
}

Free drag & wheel gestures

dragFree releases the snap points so the carousel glides to a momentum-based stop wherever the drag ends — a natural fit for a scrollable strip. Add wheelGestures to also scroll it with a trackpad or mouse wheel (horizontal swipes on a trackpad, vertical wheel on a mouse), via Embla's Wheel Gestures plugin.

import { Carousel, CarouselContent, CarouselSlide } from '@appica/ui-react/carousel'

const SLIDES = [1, 2, 3, 4, 5, 6, 7, 8]

export default function CarouselDragFree() {
  return (
    <div className="w-full max-w-xl">
      <Carousel dragFree wheelGestures align="start" containScroll="trimSnaps">
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/2 sm:basis-1/3 md:basis-1/4">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}

Progress

CarouselProgress renders a scroll progress bar (or a circular ring with variant="circular"). By default it tracks drag position, and automatically switches to counting down the autoplay timer while autoplay is playing.

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselProgress,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]

export default function CarouselProgressExample() {
  return (
    <div className="w-full max-w-xl">
      <Carousel align="start">
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/2 sm:basis-1/3">
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-square w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex items-center justify-between">
          <CarouselProgress className="w-14" />
          <div className="flex gap-2">
            <CarouselPrev
              position="none"
              render={
                <Button variant="outline" size="icon-md">
                  <ChevronLeft />
                </Button>
              }
            />
            <CarouselNext
              position="none"
              render={
                <Button variant="outline" size="icon-md">
                  <ChevronRight />
                </Button>
              }
            />
          </div>
        </div>
      </Carousel>
    </div>
  )
}

Thumbnails

Two carousels kept in sync: a main viewer and a strip of thumbnails. The useLinkedCarousels(mainApi, thumbsApi) hook wires each one's select event to the other, so navigating either drives both. Grab each engine with setApi, and read selectedIndex / scrollTo from useCarousel() inside a thumbnail to highlight and jump.

'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  useCarousel,
  useLinkedCarousels,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6, 7]

export default function CarouselThumbnails() {
  const [mainApi, setMainApi] = React.useState<CarouselApi>()
  const [thumbsApi, setThumbsApi] = React.useState<CarouselApi>()
  useLinkedCarousels(mainApi, thumbsApi)

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Carousel loop setApi={setMainApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>

      <Carousel setApi={setThumbsApi} align="start" containScroll="keepSnaps">
        <CarouselContent className="-ms-2">
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-1/4 sm:basis-1/5">
              <Thumb index={n - 1} src={`/carousel/slide-${n}.jpg`} alt={`Thumbnail ${n}`} />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}

function Thumb({ index, src, alt }: { index: number; src: string; alt: string }) {
  const { selectedIndex, scrollTo } = useCarousel()
  const isActive = index === selectedIndex
  return (
    <button
      type="button"
      onClick={() => scrollTo(index)}
      aria-label={`Go to slide ${index + 1}`}
      aria-current={isActive}
      className={`block w-full cursor-pointer overflow-hidden rounded-md border-2 transition-all duration-300 outline-none motion-reduce:transition-none ${isActive ? 'border-primary opacity-100' : 'border-transparent opacity-50 hover:opacity-80'}`}
    >
      <img src={src} alt={alt} className="aspect-square w-full object-cover" />
    </button>
  )
}

Synced carousels

useLinkedCarousels isn't limited to thumbnails — it links any two engines. Here a sliding image carousel drives a fading text carousel below it, so the caption cross-fades in as the image slides. The link is bidirectional, so the outside arrows move both engines in lockstep. Give the text carousel fade and draggable={false} so it only ever follows the images.

Sunlit summit

First light catches the ridgeline while the valley below stays in shadow — the clearest window for the summit push.

Deer in bloom

A herd grazes the high meadow at golden hour, wildflowers running all the way to the treeline.

Turquoise cove

Sea stacks shelter a quiet lagoon where the water shifts from pale sand to deep aquamarine.

Rose plains

An abandoned homestead sits alone in a sea of pink grass, wide sky stretching to the horizon.

Mirror lake

A lone peak doubles in glassy water as birds drift across a calm afternoon sky.

'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  useLinkedCarousels,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [
  {
    n: 1,
    title: 'Sunlit summit',
    body: 'First light catches the ridgeline while the valley below stays in shadow — the clearest window for the summit push.',
  },
  {
    n: 2,
    title: 'Deer in bloom',
    body: 'A herd grazes the high meadow at golden hour, wildflowers running all the way to the treeline.',
  },
  {
    n: 3,
    title: 'Turquoise cove',
    body: 'Sea stacks shelter a quiet lagoon where the water shifts from pale sand to deep aquamarine.',
  },
  {
    n: 4,
    title: 'Rose plains',
    body: 'An abandoned homestead sits alone in a sea of pink grass, wide sky stretching to the horizon.',
  },
  {
    n: 5,
    title: 'Mirror lake',
    body: 'A lone peak doubles in glassy water as birds drift across a calm afternoon sky.',
  },
]

export default function CarouselSynced() {
  const [imagesApi, setImagesApi] = React.useState<CarouselApi>()
  const [textApi, setTextApi] = React.useState<CarouselApi>()
  useLinkedCarousels(imagesApi, textApi)

  return (
    <div className="flex w-full max-w-xl flex-col gap-4 px-15">
      <Carousel loop setApi={setImagesApi}>
        <CarouselContent>
          {SLIDES.map((slide) => (
            <CarouselSlide key={slide.n}>
              <img
                src={`/carousel/slide-${slide.n}.jpg`}
                alt={slide.title}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          position="outside"
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
      </Carousel>

      <Carousel loop fade draggable={false} setApi={setTextApi}>
        <CarouselContent>
          {SLIDES.map((slide) => (
            <CarouselSlide key={slide.n}>
              <div className="min-h-24 text-center">
                <p className="text-foreground-intense text-lg font-semibold">{slide.title}</p>
                <p className="text-foreground mt-1 text-sm">{slide.body}</p>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  )
}

Parallax

A creative effect built on the engine's scroll event: each slide's inner layer is over-scaled and translated against the scroll, so the image drifts within its frame as you drag. Grab the api with setApi, then tween slideNodes() on every scroll — accounting for loop points from internalEngine().

'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]
const PARALLAX_FACTOR = 1.7

export default function CarouselParallax() {
  const [api, setApi] = React.useState<CarouselApi>()

  React.useEffect(() => {
    if (!api) return
    const layers = api.slideNodes().map((slide) => slide.querySelector<HTMLElement>('[data-parallax-layer]'))

    const tween = (_api: CarouselApi, event?: { type: string }) => {
      const engine = api.internalEngine()
      const scrollProgress = api.scrollProgress()
      const slidesInView = api.slidesInView()
      const isScroll = event?.type === 'scroll'

      api.snapList().forEach((snap, snapIndex) => {
        let diffToTarget = snap - scrollProgress
        const slidesInSnap = engine.scrollSnapList.slidesBySnap[snapIndex] ?? []

        slidesInSnap.forEach((slideIndex) => {
          if (isScroll && !slidesInView.includes(slideIndex)) return
          if (engine.options.loop) {
            engine.slideLooper.loopPoints.forEach((loopItem) => {
              const target = loopItem.target()
              if (slideIndex === loopItem.index && target !== 0) {
                const sign = Math.sign(target)
                if (sign === -1) diffToTarget = snap - (1 + scrollProgress)
                if (sign === 1) diffToTarget = snap + (1 - scrollProgress)
              }
            })
          }
          const translate = diffToTarget * (-1 * PARALLAX_FACTOR) * 100
          const layer = layers[slideIndex]
          if (layer) layer.style.transform = `translateX(${translate}%)`
        })
      })
    }

    tween(api)
    api.on('scroll', tween)
    api.on('slidefocus', tween)
    api.on('reinit', tween)
    return () => {
      api.off('scroll', tween)
      api.off('slidefocus', tween)
      api.off('reinit', tween)
    }
  }, [api])

  return (
    <div className="w-full max-w-xl">
      <Carousel loop align="center" setApi={setApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-2/3">
              <div className="aspect-3/2 overflow-hidden rounded-xl">
                <div data-parallax-layer className="size-full">
                  <img
                    src={`/carousel/slide-${n}.jpg`}
                    alt={`Slide ${n}`}
                    className="size-full scale-[1.6] object-cover"
                  />
                </div>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex justify-center gap-2">
          <CarouselPrev
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronLeft />
              </Button>
            }
          />
          <CarouselNext
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronRight />
              </Button>
            }
          />
        </div>
      </Carousel>
    </div>
  )
}

Scale

The same scroll-driven tweening, applied to transform: scale and opacity: each slide shrinks and dims in proportion to its distance from the centre, so the focused slide pops. Pairs well with align="center" and a basis that peeks the neighbours.

'use client'

import * as React from 'react'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  type CarouselApi,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5, 6]
const TWEEN_FACTOR = 1.1

const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max)

export default function CarouselScale() {
  const [api, setApi] = React.useState<CarouselApi>()

  React.useEffect(() => {
    if (!api) return
    const nodes = api.slideNodes().map((slide) => slide.querySelector<HTMLElement>('[data-scale-layer]'))

    const tween = (_api: CarouselApi, event?: { type: string }) => {
      const engine = api.internalEngine()
      const scrollProgress = api.scrollProgress()
      const slidesInView = api.slidesInView()
      const isScroll = event?.type === 'scroll'

      api.snapList().forEach((snap, snapIndex) => {
        let diffToTarget = snap - scrollProgress
        const slidesInSnap = engine.scrollSnapList.slidesBySnap[snapIndex] ?? []

        slidesInSnap.forEach((slideIndex) => {
          if (isScroll && !slidesInView.includes(slideIndex)) return
          if (engine.options.loop) {
            engine.slideLooper.loopPoints.forEach((loopItem) => {
              const target = loopItem.target()
              if (slideIndex === loopItem.index && target !== 0) {
                const sign = Math.sign(target)
                if (sign === -1) diffToTarget = snap - (1 + scrollProgress)
                if (sign === 1) diffToTarget = snap + (1 - scrollProgress)
              }
            })
          }
          const tweenValue = 1 - Math.abs(diffToTarget * TWEEN_FACTOR)
          const scale = clamp(tweenValue, 0.58, 1)
          const opacity = clamp(tweenValue, 0.24, 1)
          const node = nodes[slideIndex]
          if (node) {
            node.style.transform = `scale(${scale})`
            node.style.opacity = `${opacity}`
            node.style.transformOrigin = diffToTarget > 0 ? 'left center' : diffToTarget < 0 ? 'right center' : 'center'
          }
        })
      })
    }

    tween(api)
    api.on('scroll', tween)
    api.on('slidefocus', tween)
    api.on('reinit', tween)
    return () => {
      api.off('scroll', tween)
      api.off('slidefocus', tween)
      api.off('reinit', tween)
    }
  }, [api])

  return (
    <div className="w-full max-w-xl">
      <Carousel loop align="center" setApi={setApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n} className="basis-2/3">
              <div data-scale-layer className="transition-none">
                <img
                  src={`/carousel/slide-${n}.jpg`}
                  alt={`Slide ${n}`}
                  className="aspect-3/2 w-full rounded-xl object-cover"
                />
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <div className="mt-5 flex justify-center gap-2">
          <CarouselPrev
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronLeft />
              </Button>
            }
          />
          <CarouselNext
            position="none"
            render={
              <Button variant="outline" size="icon-md">
                <ChevronRight />
              </Button>
            }
          />
        </div>
      </Carousel>
    </div>
  )
}

Overlaid controls

Set light on CarouselPagination / CarouselProgress (and a light-variant Button for the arrows) when the controls sit over imagery, so they read against a dark scrim instead of the page background.

Sunlit summit

Aurora Range

Deer in bloom

Meadowvale Alps

Turquoise cove

Azure Isles

Rose plains

Crimson Flats

Mirror lake

Stillwater Valley

import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [
  { n: 1, title: 'Sunlit summit', caption: 'Aurora Range' },
  { n: 2, title: 'Deer in bloom', caption: 'Meadowvale Alps' },
  { n: 3, title: 'Turquoise cove', caption: 'Azure Isles' },
  { n: 4, title: 'Rose plains', caption: 'Crimson Flats' },
  { n: 5, title: 'Mirror lake', caption: 'Stillwater Valley' },
]

export default function CarouselLight() {
  return (
    <div className="w-full max-w-xl">
      <Carousel loop className="overflow-hidden rounded-xl">
        <CarouselContent>
          {SLIDES.map((slide) => (
            <CarouselSlide key={slide.n}>
              <div className="relative aspect-3/2 w-full">
                <img src={`/carousel/slide-${slide.n}.jpg`} alt={slide.title} className="size-full object-cover" />
                <div className="absolute inset-0 bg-linear-to-t from-black/70 via-black/10 to-transparent" />
                <div className="absolute inset-s-0 bottom-0 p-5">
                  <p className="text-lg font-semibold text-white">{slide.title}</p>
                  <p className="text-sm text-white/70">{slide.caption}</p>
                </div>
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="light" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="light" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination light className="absolute inset-x-0 bottom-5 justify-center" />
      </Carousel>
    </div>
  )
}

Controlled with the api

Capture the Embla instance with setApi to drive the carousel imperatively and mirror its state elsewhere. Here external buttons call goToPrev() / goToNext() and a counter subscribes to the select event to show the current position.

Slide 1 of 0

'use client'

import * as React from 'react'
import { Carousel, CarouselContent, CarouselSlide, type CarouselApi } from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselControlled() {
  const [api, setApi] = React.useState<CarouselApi>()
  const [current, setCurrent] = React.useState(0)
  const [count, setCount] = React.useState(0)

  React.useEffect(() => {
    if (!api) return
    setCount(api.snapList().length)
    setCurrent(api.selectedSnap())
    const onSelect = () => setCurrent(api.selectedSnap())
    api.on('select', onSelect)
    return () => {
      api.off('select', onSelect)
    }
  }, [api])

  return (
    <div className="w-full max-w-xl">
      <Carousel loop setApi={setApi}>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <img
                src={`/carousel/slide-${n}.jpg`}
                alt={`Slide ${n}`}
                className="aspect-3/2 w-full rounded-xl object-cover"
              />
            </CarouselSlide>
          ))}
        </CarouselContent>
      </Carousel>
      <div className="mt-5 flex items-center justify-between">
        <Button variant="outline" size="icon-md" aria-label="Previous slide" onClick={() => api?.goToPrev()}>
          <ChevronLeft />
        </Button>
        <p className="text-sm tabular-nums">
          Slide {current + 1} of {count}
        </p>
        <Button variant="outline" size="icon-md" aria-label="Next slide" onClick={() => api?.goToNext()}>
          <ChevronRight />
        </Button>
      </div>
    </div>
  )
}

Next.js Image

Render slides with next/image for automatic optimization. Give each slide a fixed-aspect wrapper and use fill with a matching sizes so the image resolves the right source; mark the first slide priority since it's the LCP candidate.

import Image from 'next/image'
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselPrev,
  CarouselNext,
  CarouselPagination,
} from '@appica/ui-react/carousel'
import { Button } from '@appica/ui-react/button'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const SLIDES = [1, 2, 3, 4, 5]

export default function CarouselNextImage() {
  return (
    <div className="w-full max-w-xl pb-8">
      <Carousel loop>
        <CarouselContent>
          {SLIDES.map((n) => (
            <CarouselSlide key={n}>
              <div className="relative aspect-3/2 w-full overflow-hidden rounded-xl">
                <Image
                  src={`/carousel/slide-${n}.jpg`}
                  alt={`Slide ${n}`}
                  fill
                  sizes="(max-width: 640px) 100vw, 576px"
                  className="object-cover"
                  priority={n === 1}
                />
              </div>
            </CarouselSlide>
          ))}
        </CarouselContent>
        <CarouselPrev
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronLeft />
            </Button>
          }
        />
        <CarouselNext
          render={
            <Button variant="outline" size="icon-md" className="rounded-full">
              <ChevronRight />
            </Button>
          }
        />
        <CarouselPagination className="absolute inset-x-0 top-full mt-5 justify-center" />
      </Carousel>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

A horizontal carousel reverses its drag axis and starting edge, so slides flow from the right and the Previous/Next arrows swap sides. Give the arrow buttons direction-appropriate icons and aria-labels. Vertical carousels are unaffected by direction. For setup details and caveats, see the RTL guide.

API reference

Carousel is a compound component. The root creates the Embla engine and shares it through context; the parts read from it. Flat props on the root mirror Embla options and toggle its official plugins.

Carousel

The root. Creates the engine, provides context, and renders a <div role="region">.

Prop	Type	Default	Description
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Scroll axis. Maps to Embla's `axis`; exposed as `data-orientation`.
`loop`	`boolean`	`false`	Wrap around from the last slide to the first.
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Where slides settle within the viewport.
`slidesToScroll`	`number \| 'auto'`	`1`	How many slides advance per step. `'auto'` groups by how many fit the viewport.
`containScroll`	`false \| 'trimSnaps' \| 'keepSnaps'`	`'trimSnaps'`	Clamp scrolling so there's no empty space at the edges. `false` disables containment.
`dragFree`	`boolean`	—	Release snap points; glide to a momentum stop.
`startSnap`	`number`	—	Index of the slide to start on.
`active`	`boolean`	`true`	When `false`, the engine is inert (no drag/snap) — e.g. to disable at a breakpoint.
`draggable`	`boolean`	`true`	Whether pointer dragging is enabled (Embla's `watchDrag`).
`duration`	`number`	—	Scroll animation duration (Embla's ease). Forced to `0` under reduced motion.
`options`	`EmblaOptionsType`	—	Escape hatch: a raw Embla options object, merged last so it wins over the flat props.
`autoplay`	`boolean \| AutoplayOptions & { resumeAfter?: number }`	—	Enable the Autoplay plugin. `resumeAfter` (ms) restarts the timer after user interaction.
`autoScroll`	`boolean \| AutoScrollOptions & { resumeAfter?: number }`	—	Enable continuous Auto Scroll. Mutually exclusive with `autoplay`; paused under reduced motion.
`autoHeight`	`boolean \| AutoHeightOptions`	—	Enable the Auto Height plugin; animates the viewport to each slide's height.
`fade`	`boolean \| FadeOptions`	—	Enable the Fade plugin (cross-fade instead of slide). Best with one slide per view.
`classNames`	`boolean \| ClassNamesOptions`	—	Enable the Class Names plugin, which toggles `snapped` / `inView` classes on slides.
`accessibility`	`boolean \| AccessibilityOptions`	`true`	Keyboard/ARIA plugin for the viewport. Set `false` to opt out.
`wheelGestures`	`boolean \| WheelGesturesOptions`	`false`	Enable trackpad / mouse-wheel scrolling.
`plugins`	`EmblaPluginType[]`	—	Additional Embla plugins to append.
`setApi`	`(api: CarouselApi) => void`	—	Receives the Embla instance once initialized — for imperative control.
`onReInit`	`(api: CarouselApi) => void`	—	Fires on init and whenever the engine re-initializes.
`onSelect`	`(api: CarouselApi) => void`	—	Fires when the selected snap changes.
`onScroll`	`(api: CarouselApi) => void`	—	Fires continuously while scrolling.
`light`	`boolean`	`false`	Hint stored in context for light-on-dark surfaces; read via `useCarousel()`.
`aria-label`	`string`	`'Carousel'`	Accessible name for the region (native attribute, forwarded to the root).
`className`	`string`	—	Extra classes on the root, merged via `tailwind-merge`.

The root also forwards remaining native <div> attributes.

CarouselContent

The scroll viewport plus the flex track that holds the slides. Renders two nested <div>s. className lands on the inner track — a common place to set the viewport height for vertical carousels (e.g. h-72).

Prop	Type	Default	Description
`className`	`string`	—	Extra classes on the track. Also forwards native attrs.
`children`	`ReactNode`	—	The `CarouselSlide`s.

CarouselSlide

One slide / snap point. Renders a <div role="group"> with basis-full by default — override basis-* to change how many slides show per view.

Prop	Type	Default	Description
`className`	`string`	—	Extra classes — set `basis-*` here. Also forwards native attrs.

CarouselPrev / CarouselNext

The previous/next arrows. Each renders an unstyled <button> (auto-disabled at the ends) inside a positioner. Pass your own element — usually a Button — through render.

Prop	Type	Default	Description
`position`	`'inside' \| 'outside' \| 'outside-half' \| 'none'`	`'inside'`	Where the arrow sits relative to the viewport. `none` drops absolute positioning so you can place it.
`disabled`	`boolean`	—	Force-disable, on top of the automatic end-of-track disabling.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Element to render as the arrow. `state` exposes `{ disabled, direction }`.
`className`	`string`	—	Classes on the positioner (not the button). Put button styling on the `render` element.

Composition (render, className) is powered by Base UI's useRender. Remaining button attributes (onClick, aria-label, …) are forwarded to the button and merged with the internal scroll handler.

CarouselPagination

A row (or column) of clickable bullets, one per snap point. Renders a <div role="tablist">; returns null when there's a single snap. The active bullet fills as an autoplay timer indicator while autoplay is playing.

Prop	Type	Default	Description
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Lay the bullets out in a row or a column.
`light`	`boolean`	`false`	Light-on-dark styling for use over imagery.
`className`	`string`	—	Extra classes. Also forwards native attrs.

CarouselProgress

A scroll/autoplay progress indicator. Renders a bar by default, or a ring with variant="circular".

Prop	Type	Default	Description
`source`	`'auto' \| 'autoplay' \| 'scroll'`	`'auto'`	What drives the fill. `'auto'` counts down autoplay while it plays, otherwise tracks scroll position.
`variant`	`'bar' \| 'circular'`	`'bar'`	Straight bar or circular ring.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Fill direction for the bar variant.
`light`	`boolean`	`false`	Light-on-dark styling for use over imagery.
`className`	`string`	—	Extra classes. Also forwards native attrs.

useCarousel()

Hook that returns the carousel context from inside a Carousel: api (the Embla instance), navigation callbacks (scrollPrev, scrollNext, scrollTo), and reactive state (selectedIndex, scrollSnaps, canScrollPrev, canScrollNext, orientation, direction, plus autoplay state). Per-frame scroll progress is exposed as a subscribeScrollProgress / getScrollProgress pair (subscribe with useSyncExternalStore so only readers re-render — this is what CarouselProgress uses); read slides in view from api.slidesInView(). Throws if used outside a Carousel.

useLinkedCarousels(mainApi, thumbsApi)

Bidirectionally syncs two carousels' selected snaps — the classic main-plus-thumbnails pattern. Wires each engine's select event to goTo the other. Both apis may be undefined initially (while waiting on setApi); the effect re-runs once both resolve.

Accessibility

The root is a role="region" with aria-roledescription="carousel" and an aria-label (native attribute, default "Carousel"); each slide is a role="group" with aria-roledescription="slide".
The Accessibility plugin (on by default) makes the viewport keyboard-operable — focus it and use the arrow keys to navigate.
CarouselPrev / CarouselNext carry aria-labels ("Previous slide" / "Next slide") and are disabled at the ends of a non-looping carousel. When you supply a render element, keep an accessible name and localize it as needed.
CarouselPagination is a role="group" labelled "Choose slide to display" of bullet <button>s, each labelled "Go to slide N" with aria-current on the active one.
Progress fills, the autoplay indicator, and scroll animations honour prefers-reduced-motion — drag snaps instantly and Auto Scroll is disabled.
Give image slides meaningful alt text (or alt="" for purely decorative imagery).