Carousel Kit

When to use it

Use it to build your own carousel with the same accessible parts the other carousel components share. Pick a ready-made carousel (thumbnails, fade, autoplay) first; reach for the kit when none fits.

Do not use it for a plain scrolling list with no paging: a native overflow row (see Carousel Snap) is lighter.

Installation

pnpmnpmyarnbun
pnpm dlx shadcn@latest add https://ui.tealmac.com/r/carousel-kit.json
Copy

Usage

Copyimport {
  Carousel,
  CarouselCounter,
  CarouselDots,
  CarouselNext,
  CarouselPrevious,
  CarouselSlide,
  CarouselTrack,
  CarouselViewport,
} from "@/components/ui/carousel-kit"

Copy<Carousel label="How it works" opts={{ loop: false }}>
  <CarouselViewport>
    <CarouselTrack>
      <CarouselSlide>One</CarouselSlide>
      <CarouselSlide>Two</CarouselSlide>
    </CarouselTrack>
  </CarouselViewport>
  <CarouselPrevious />
  <CarouselDots />
  <CarouselNext />
</Carousel>

Props

| Part | Prop | Type | Default | Description | | ------------------- | --------------- | --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | Carousel | label | string | required | Accessible name of the region, announced as "<label>, carousel". | | Carousel | orientation | "horizontal" | "vertical" | "horizontal" | Scroll axis. Vertical swaps Left/Right for Up/Down. | | Carousel | opts | EmblaOptionsType | {} | Embla options (loop, align, dragFree, slidesToScroll...). axis and direction are set for you. | | Carousel | setApi | (api) => void | - | Receives the Embla API once it exists. | | Carousel | onIndexChange | (index) => void | - | Called with the snap index when the selection changes. | | CarouselSlide | - | div props | - | Gets role group, roledescription slide and the label "2 of 5" from its position in <CarouselTrack>. | | CarouselDots | label | string | "Choose a slide" | Name of the group of dots. | | useCarousel | - | () => CarouselState | - | Index, count, canPrev, canNext, scrollTo, prev, next, rtl, reducedMotion and the API. | | useSlideProximity | - | (api, { apply, enabled }) | - | Calls apply(node, distance, index) every frame, with distance 0 at the centre. Drive transforms with CSS variables. | | CarouselEffect | apply | (node, distance, index) => void | - | Component form of useSlideProximity; place inside <Carousel>. |

Keyboard

• Left / Right (Up / Down when vertical): previous or next slide. Flipped in right-to-left pages.
• Home / End: first or last slide.
• Arrow keys are ignored while typing in an input, textarea or select inside the carousel.

Accessibility

• The root is a region with aria-roledescription="carousel" and the label you give it.
• Every slide is a group with aria-roledescription="slide" and a name such as "2 of 5".
• The track is aria-live="polite" unless the carousel moves by itself (autoplay switches it off).
• Focus moving into an off-screen slide brings that slide into view and undoes the browser's own scroll.
• Dots are buttons with aria-current, 24px or more to tap.

Testing

The component ships with a Testing Library test (carousel-kit.test.tsx). Embla needs layout to count snaps, and jsdom has none, so the repo's mockCarouselLayout helper gives the viewport and slides real sizes in tests.