Carousel

A transform-based carousel component. Uses CSS transforms (translateX) for smooth, performant sliding with no external dependencies.

Features

• ✅ CSS transform-based: Smooth translateX animations
• ✅ No dependencies: Fully self-contained
• ✅ Touch/swipe gestures: Drag slides with mouse or touch
• ✅ Infinite loop: Optional looping
• ✅ Autoplay: With configurable delay and pause on hover/focus
• ✅ Responsive: Media query-based breakpoints
• ✅ Pagination: Dots, fraction, and progress bar
• ✅ Keyboard navigation: Arrow keys, Home, and End support
• ✅ Accessible: ARIA attributes, live region announcements, reduced motion support

Basic Example

Slide 1

Slide 2

Slide 3

Multiple Slides Per View

Show multiple slides at once with slidesPerView.

1

2

3

4

5

6

Pagination Dots

Add pagination dots for visual page indicators.

Slide 1

Slide 2

Slide 3

Slide 4

Pagination Fraction

Show current page 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. Use loop: true with autoplay so slides cycle continuously.

Auto 1

Auto 2

Auto 3

Loop Mode

Enable infinite looping with loop: true.

Loop 1

Loop 2

Loop 3

Responsive Breakpoints

Use media query strings as keys for breakpoint-specific settings.

1

2

3

4

5

6

Data Attributes

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="
  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	1	Number of slides visible at once
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	Snap to nearest slide instead of using drag direction
threshold	number	20	Minimum drag distance to trigger slide change
resistance	boolean	true	Resistance effect at edges when not looping
autoplay	boolean | AutoplayConfig	false	Enable autoplay
speed	number	300	Transition speed in ms
breakpoints	object	{}	Responsive breakpoint settings
a11y	A11yConfig	see below	Accessibility configuration

Autoplay Config

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

A11y Config

{
  enabled?: boolean           // Enable accessibility features (default: true)
  prevSlideMessage?: string   // Aria label for prev button (default: 'Previous slide')
  nextSlideMessage?: string   // Aria label for next button (default: 'Next slide')
}

Breakpoints

{
  '(min-width: 640px)': { slidesPerView: 2 },
  '(min-width: 1024px)': { slidesPerView: 3, spaceBetween: 24 }
}

State Properties

Access via $carousel in Alpine expressions (e.g., $carousel.activeIndex):

Property	Type	Description
activeIndex	number	Index of the first visible slide
pageIndex	number	Same as activeIndex (each page is one slide position)
firstVisibleIndex	number	Index of the first visible slide
lastVisibleIndex	number	Index of the last visible slide
totalSlides	number	Total number of slides
totalPages	number	Number of navigable positions (totalSlides - slidesPerView + 1)
canGoPrev	boolean	Whether previous navigation is possible
canGoNext	boolean	Whether next navigation is possible
progress	number	Progress percentage (0 to 100)
isAutoplayPaused	boolean	Whether autoplay is currently paused

Methods

Method	Description
goTo(index, smooth?)	Go to specific slide
next()	Go to next slide
prev()	Go to previous slide
update(settings)	Update carousel settings at runtime
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 }

Parts

Part	Description
viewport	Overflow container
track	Flex container with translateX (wraps slides)
slide	Individual slide element
prev-button	Previous slide button
next-button	Next slide button
pagination	Pagination bullet (requires page index value)
pagination-fraction	Fraction display (e.g., "1 / 3")
pagination-progress	Progress bar element

Slide Scope ($slide)

Property	Type	Description
index	number	Slide index
isActive	boolean	Whether this is the active slide
isPrev	boolean	Whether this is the previous slide
isNext	boolean	Whether this is the next slide
isVisible	boolean	Whether the slide is in the visible range
activate()	function	Navigate to this slide

Pagination Scope ($pagination)

Property	Type	Description
index	number	Page index
isActive	boolean	Whether this is the active page
label	string	Display label (e.g., "1")
goTo()	function	Navigate to this page

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