Carousel

A slideshow component for cycling through content with auto-play, swipe gestures, and navigation controls.

Import#

import { Carousel } from "asheeui";

Usage#

import { Carousel } from "asheeui";

const slides = [
	{
		id: "1",
		content: (
			<div className="flex h-40 items-center justify-center bg-primary/10">
				Slide 1
			</div>
		),
	},
	{
		id: "2",
		content: (
			<div className="flex h-40 items-center justify-center bg-secondary/10">
				Slide 2
			</div>
		),
	},
	{
		id: "3",
		content: (
			<div className="flex h-40 items-center justify-center bg-success/10">
				Slide 3
			</div>
		),
	},
];

export default function Basic() {
	return (
		<div className="w-full max-w-2xl">
			<Carousel items={slides} />
		</div>
	);
}

Examples#

Variant#

Size#

Radius#

Auto-play#

Loop#

With controls#

With indicators#

Pause on hover#

Without animation#

Controlled#

Custom controls#

Props#

* Falls back through Global Configuration if not set. See below.

CarouselItem#

Global Configuration#

Carousel reads defaults from four places, in this order of precedence:

1. Instance prop: set directly on <Carousel />
2. Component config: components.carousel in your ashee.config
3. Theme default: defaultVariant / defaultRadius in your ashee.config
4. Built-in fallback: component's internal default values

Component config#

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    carousel: {
      variant: "bordered",
      size: "md",
      radius: "lg",
      autoPlay: true,
      autoPlayInterval: 3000,
      loop: true,
      showControls: true,
      showIndicators: true,
      pauseOnHover: true,
    },
  },
};

Built-in fallbacks#

{
  size: "md",
  variant: "bordered",
  radius: "lg",
  autoPlay: false,
  autoPlayInterval: 5000,
  loop: true,
  showControls: true,
  showIndicators: true,
  pauseOnHover: true,
}

Accessibility#

• Uses native button elements for controls with proper aria-label attributes
• Supports keyboard navigation via focus management
• Dot indicators include aria-label with slide number
• Touch gestures support pointer events
• Disabled controls prevent interaction in non-looping carousels
• Implements focus-visible rings for keyboard navigation

Notes#

• Items vs Children: Use items for structured data or children for simple content. If both are provided, items takes precedence.
• Controlled vs Uncontrolled: Use index/onIndexChange for controlled usage, or defaultIndex for uncontrolled.
• Swipe Support: The carousel supports touch and mouse drag gestures with a 50px threshold for swipe detection.
• Auto-play: Auto-play pauses when the carousel is hovered (if pauseOnHover is enabled) or when dragging.
• Looping: When loop is false, navigation controls are disabled at the first and last slides.
• Performance: For large carousels with many slides, consider using disableAnimation to reduce layout shifts.