Carousel

A flexible carousel component with touch gestures, keyboard navigation, and multiple display modes.

Features

• ✅ Touch/swipe gestures: Drag slides with mouse or touch
• ✅ Keyboard navigation: Arrow keys, Home, and End support
• ✅ Flexible layouts: Fixed slides per view or auto-width slides
• ✅ Autoplay: Optional automatic sliding with pause on hover/focus
• ✅ Loop mode: Infinite looping of slides
• ✅ Pagination: Multiple styles (dots, fraction, progress bar)
• ✅ Responsive breakpoints: Different settings per screen size
• ✅ Accessible: Full keyboard support and ARIA attributes

Basic Example

Slide 1

Slide 2

Slide 3

Multiple Slides Per View

Show multiple slides at once with slidesPerView.

1

2

3

4

5

Auto-Width Slides

Use slidesPerView: 'auto' for slides with custom widths.

200px

300px

250px

180px

Pagination Dots

Add pagination dots for visual slide indicators.

Slide 1

Slide 2

Slide 3

Slide 4

Pagination Fraction

Show current slide position as a fraction.

Slide 1

Slide 2

Slide 3

Progress Bar

Display a progress bar showing carousel position.

Slide 1

Slide 2

Slide 3

Slide 4

Autoplay

Enable automatic slide progression.

Auto 1

Auto 2

Auto 3

Loop Mode

Enable infinite looping of slides.

Loop 1

Loop 2

Loop 3

Data Attributes

All parts include data attributes for styling based on state.

Slide Attributes

• data-active - Current active slide
• data-prev - Previous slide
• data-next - Next slide
• data-visible - Slide is visible in viewport
• data-index - Slide index number

Pagination Attributes

• data-active - Active pagination bullet

Example Styling

<div x-carousel:slide class="
  shrink-0
  w-full
  data-active:scale-105
  data-active:shadow-lg
  transition-transform
">
  Slide content
</div>

<button x-carousel:pagination class="
  data-active:bg-blue-600
  data-active:w-6
">
</button>

API Reference

Props

Prop	Type	Default	Description
slidesPerView	number | 'auto'	1	Number of slides visible or 'auto' for custom widths
spaceBetween	number	0	Space between slides in pixels
loop	boolean	false	Enable infinite looping
keyboard	boolean	true	Enable keyboard navigation
draggable	boolean	true	Enable mouse/touch drag
freeMode	boolean	false	Disable snap to slides
snapToSlides	boolean	true	Snap to closest slide after drag
threshold	number	10	Minimum drag distance to trigger slide
resistance	boolean	true	Resistance at carousel edges
autoplay	boolean | AutoplayConfig	false	Enable autoplay
speed	number	300	Transition speed in ms
breakpoints	object	{}	Responsive breakpoint settings

Autoplay Config

{
  delay: number          // Delay between slides in ms
  pauseOnHover?: boolean // Pause on mouse hover
  pauseOnFocus?: boolean // Pause when focused
}

Breakpoints

{
  640: { slidesPerView: 2 },
  1024: { slidesPerView: 3, spaceBetween: 24 }
}

Methods

Access via $carousel in Alpine expressions:

Method	Description
goTo(index, smooth?)	Go to specific slide
next()	Go to next slide
prev()	Go to previous slide
startAutoplay()	Start autoplay
stopAutoplay()	Stop autoplay
pauseAutoplay()	Pause autoplay temporarily
resumeAutoplay()	Resume autoplay

Events

Event	Description	Payload
slidechange	Fired when active slide changes	{ index: number }
slide:visibility	Fired when slide visibility changes	{ index: number, isVisible: boolean }

Parts

Part	Description
root	Root container element
viewport	Scrollable viewport container
slide	Individual slide element
prev-button	Previous slide button
next-button	Next slide button
pagination	Pagination bullet (requires index value)
pagination-fraction	Fraction display (e.g., "1 / 5")
pagination-progress	Progress bar element

Accessibility

The carousel follows accessibility best practices:

• Keyboard navigation: Arrow keys to navigate, Home/End for first/last
• ARIA attributes: Proper roles and labels for screen readers
• Focus management: Keyboard focus support with visible indicators
• Reduced motion: Respects prefers-reduced-motion setting
• Announcements: Live region announces slide changes

Keyboard Interactions

Key	Action
ArrowLeft	Go to previous slide
ArrowRight	Go to next slide
Home	Go to first slide
End	Go to last slide
Tab	Focus next interactive element