Carousel

v0.1.21

Ready for Production

Catalyst Carousel is a flexible, accessible carousel built on top of Embla Carousel — giving you swipe interactions, keyboard navigation, and horizontal or vertical orientations with zero configuration.

Installation

npm install @pmi/catalyst-carousel

Common Patterns

Loop

Enable infinite looping by passing options={{ loop: true }} to CarouselRoot.

Vertical Orientation

Create a vertical scrolling carousel with the orientation="vertical" prop.

Drag Free

Allow free-form dragging without snap points using options={{ dragFree: true }}.

Variable Widths

Control individual slide widths with Tailwind basis-* utilities on CarouselItem.

Right-to-Left

Support RTL layouts by wrapping in a dir="rtl" container and passing options={{ direction: 'rtl' }}.

Slides to Scroll

Scroll multiple slides at once with options={{ slidesToScroll: 2 }}. Assign matching snapIndex values to group items.

Plugins

Autoplay

Automatically advance slides with the autoplay plugin.

Auto-scroll

Continuously scroll slides without snapping using the auto-scroll plugin.

Testimonial Carousel

A carousel layout optimized for displaying testimonials with images and text.

Preview

I started in market research, but I wanted to get into something that was going to scratch the creative part of my brain. My PMP helped open doors. Now, I work at Fender where I'm helping make really cool things come to fruition.

Brandon Ramirez, PMP

Senior Creative Project Manager, Fender

Earning my PMP was life changing. It gave me the confidence I needed to start my own business. I now own two successful Brazilian steakhouses. My businesses are my dream project.

Josiane Ballin, PMP

Project Manager, Entrepreneur

I always tell Project Managers to seek out community. I have what I call my coven. And they are my backbone. It's important to talk about the work that you do, and also to invest in your education.

Stephanie Bedford, PMP

Senior Producer, Gaming & Entertainment

PDP Carousel with Conditional Drag

Disable drag on larger screens by conditionally setting options={{ watchDrag: false }}.

API Reference

Carousel is a compound component built on Embla Carousel primitives. The sections below summarize the API surface for each part.

CarouselRoot

The root container that provides context and configuration for the carousel. Accepts all standard div attributes, and asChild for composition with Radix Slot.

CarouselContent

Container for carousel items that manages the scrollable area. Accepts all standard div attributes and forwards ref.

CarouselItem

Individual carousel slide container. Use Tailwind basis-* utilities (basis-1/2, basis-4/5, etc.) to control slide width.

CarouselPrevious

Button to navigate to the previous slide. Accepts all standard button attributes. Receives data-[disabled] when at the boundary in non-loop mode.

CarouselNext

Button to navigate to the next slide. Accepts all standard button attributes. Receives data-[disabled] when at the boundary in non-loop mode.

CarouselControls

Layout container for pagination dots and navigation buttons. Accepts all standard div attributes.

CarouselPagination

Container for pagination dot indicators. Accepts all standard div attributes.

CarouselPaginationDot

Individual pagination indicator. Receives data-[selected] when its snap point is active.

CarouselAnnounce

Visually hidden live region that announces slide changes to screen readers. Always include this in every carousel for accessibility.

Accessibility

Keyboard Interactions

ARIA

• CarouselAnnounce renders a visually hidden live region — always include it so screen readers announce slide changes.
• Navigation buttons receive descriptive labels; provide aria-label if using icon-only buttons without visible text.
• data-[disabled] is applied to previous/next buttons at the carousel boundary — assistive technology reads these as disabled.
• Catalyst adds styling and token-based focus indicators; Embla provides the underlying scroll and interaction semantics.

Choosing the Right Component

Use Carousel when you need a scrollable, swipeable sequence of items with pagination controls. Reach for a different component when:

Related

• Card
• Button
• Tabs